Pular para o conteúdo principal

@starlightcms/js-sdk

Index

API Entities

Client

Data Fields

Errors

Functions

Instances

Request Parameters

Selectors

Type Aliases

Instances

Internal Types

Selectors

Visual Data Blocks

Client

DynamicStarlightClient

DynamicStarlightClient<T>: StarlightClient<T> & { [ K in keyof T ]: DynamicModelInstance<T[K]> }

This type adds support for the dynamic syntax to the StarlightClient interface, which allows users to create DynamicModelInstances dynamically. See StarlightClient to learn which methods it provides. Also see Dynamic Instances documentation to learn more about the dynamic syntax.

This allows TypeScript to correctly type all models defined by the user in the DefaultModelDefinition type, aside from letting the user using any “unknown” model slug, which is provided by the WorkspaceModelDefinition type.

This type is only aware of the DefaultModelDefinition type because the StarlightClient uses it by default when no model definition type is passed.

Type parameters

  • T: WorkspaceModelDefinition

StarlightConfig

StarlightConfig: { baseUrl?: BaseUrl; debug?: boolean; workspace?: string }

The available options to configure a StarlightClient.

workspace is required when creating new clients or configuring the default client.

Type declaration

  • optionalbaseUrl?: BaseUrl

    The Starlight Query API URL, including the version, and without a trailing slash. Defaults to the production Query API URL.

    You only need to set this if you’re not using Starlight’s production APIs.

  • optionaldebug?: boolean

    When true, logs all API requests in the console. Defaults to false.

  • optionalworkspace?: string

    The ID of the workspace that the client should use to request data.

    Note: the current APIs only support using workspace IDs as identifiers, and not slugs. Slug support will be added in the future. You can find the workspace ID in the left-side menu on the Starlight interface or below the workspace name in the workspace list.

constdefault

default: DynamicStarlightClient<DefaultModelDefinition & WorkspaceModelDefinition> = ...

This is the default object exported by the SDK module, which is a pre-created StarlightClient. In the docs, this is called the “global SDK client”. If your application only requests data from a single Starlight workspace, using this client is easier than creating a new one using makeStarlightClient.

Using the default client is as easy as importing the SDK:

// "Starlight" below is the default client.
import Starlight from '@starlightcms/js-sdk'

const response = await Starlight.posts.entries.list()

You need to configure the default workspace before using it. See StarlightClient.configure to learn more.

Data Fields

BooleanField

BooleanField: boolean

Represents a Boolean Field returned by the API.

Field types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

HtmlField

HtmlField: string

Represents a HTML Field returned by the API.

Field types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

MediaField

MediaField: MediaObject

Represents a Media Field returned by the API.

Field types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

RelationField

RelationField<T>: Relation<T>

Represents a Relation Field returned by the API.

Field types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

Type parameters

  • T

StringField

StringField: string

Represents a String Field returned by the API.

Field types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

TextField

TextField: string

Represents a Text Field returned by the API.

Field types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

VisualField

VisualField: VisualData

Represents a Visual Field returned by the API.

Field types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

Other

BaseUrl

BaseUrl: https://query.starlight.sh/v2 | string

This is a utility type that allows any string to be used as a URL, but provides a default one which can be used by IDEs to provide auto-completion. The default URL points to version 2 of the Query API.

Instances

DynamicCollectionSelector

DynamicCollectionSelector: CollectionSelector & {}

A Selector that provide all CollectionSelector methods and adds support for creating CollectionInstances using the dynamic syntax.

See CollectionSelector to view all available methods.

See Dynamic Instances documentation to learn more about the dynamic syntax.

@example

Accessing a CollectionInstance using the dynamic syntax.

import Starlight from '@starlightcms/js-sdk'

// "sliders" below will be a CollectionInstance.
const response = await Starlight.collections.sliders.list()

DynamicModelCategorySelector

DynamicModelCategorySelector<D>: ModelCategorySelector & {}

A Selector that provide all ModelCategorySelector methods and adds support for creating ModelCategoryInstances using the dynamic syntax.

See ModelCategorySelector to view all available methods. You can use a DynamicModelCategorySelector by accessing ModelInstance.categories.

See Dynamic Instances documentation to learn more about the dynamic syntax.

@example

Accessing a ModelCategorySelector using the dynamic syntax on a model of slug “posts”

import Starlight from '@starlightcms/js-sdk'

// "articles" below will be a ModelCategorySelector.
const response = await Starlight.posts.categories.articles.list()

Type parameters

DynamicModelInstance

DynamicModelInstance<D>: ModelInstance<D> & {}

An Instance that provide all ModelInstance methods and adds support for creating ModelCategoryInstances using the dynamic syntax.

See ModelInstance to view all available methods.

See Dynamic Instances documentation to learn more about the dynamic syntax.

@example

Accessing a ModelCategoryInstance using the dynamic syntax.

import Starlight from '@starlightcms/js-sdk'

// "articles" below will be a ModelCategoryInstance.
const response = await Starlight.posts.articles.list()

Type parameters

Internal Types

QueryableFields

QueryableFields<D>: { [ K in keyof D as `field:${string & K}` ]?: string | boolean }

Utility type that creates a string map of all fields of the given SerializedData type with the field: prefix. This syntax allows to filter specific fields when listing Entries:

  • Text fields can be filtered by a string query. This works just like passing a query parameter, but it only applies to one field.
  • Boolean fields can be filtered by “true” or “false”.

If a request uses this type, it means that this syntax can be used in their parameters:

import Starlight from '@starlightcms/js-sdk'

const response = await Starlight.posts.entries.list({
  // EntrySelector.list() supports the "field:foo" syntax:
  'field:content': 'hello world',
  'field:is_featured': true,

  // EntrySelector.list() also support other parameters,
  // which are passed in this object too:
  page: 42,
  limit: 20,
})
@remark

The information below is only useful for SDK maintainers.

This type receives a SerializedData-like structure, like an object. For instance, for an Entry with fields “content” and “summary”, the generated type would look like this:

type GeneratedType = {
  'field:content'?: string
  'field:summary'?: string
}

However, note that QueryableFields receive a SerializedData, not an Entry:

import { VisualField, StringField } from '@starlightcms/js-sdk'

type EntryFields = {
  content: VisualField
  summary: StringField
}

type MyEntry = Entry<EntryFields>

// Error TS2344: Type does not satisfy the constraint 'SerializedData'
type GeneratedType = QueryableFields<MyEntry>

// Works!
type GeneratedType = QueryableFields<EntryFields>

This type is only useful to request methods that support field querying using the “field:foo” syntax.

Type parameters

SerializedData

SerializedData: Record<string, unknown> | undefined

Represents content data returned by either an Entry or Singleton entity from the API.

This is a utility type used internally by the SDK and you don’t need to use it. Its purpose is to constraint Entry and Singleton data to the shape of a JS object.

WithQueryableFieldsOnModelables

WithQueryableFieldsOnModelables<T>: T extends Entry<never> | Singleton<never> ? QueryableFields<T[data]> : never

Utility type that return QueryableFields if the given type T is an Entry or a Singleton, but generates an empty object otherwise.

Fun fact: internally, Entries and Singletons have parent Models, which is why they are called “modelables” here.

Type parameters

  • T

Selectors

DynamicModelSelector

DynamicModelSelector<T>: ModelSelector & { [ K in keyof T ]: DynamicModelInstance<T[K]> }

A Selector that provide all ModelSelector methods and adds support for creating DynamicModelInstances using the dynamic syntax.

See ModelSelector to view all available methods.

See Dynamic Instances documentation to learn more about the dynamic syntax.

@example

Accessing a DynamicModelInstance using the dynamic syntax.

import Starlight from '@starlightcms/js-sdk'

// "posts" below will be a DynamicModelInstance.
const response = await Starlight.models.posts.entries.list()

Type parameters

  • T: WorkspaceModelDefinition

Visual Data Blocks

VideoBlock

VideoBlock: { caption?: string; html: string; service: SupportedServices; type: embed; url: string; videoId: string; width: BlockWidth }

Represents a Video block, which is used to render embed video elements.

Type declaration

  • optionalcaption?: string
  • html: string
  • service: SupportedServices
  • type: embed
  • url: string
  • videoId: string
  • width: BlockWidth