@starlightcms/js-sdk 0.10.0 → 0.11.0

package/dist/cjs/selectors/Search/types.d.ts

@@ -1,14 +1,87 @@
-import { Entry, SerializedData, StarlightListResponse } from '../../types';
-export declare type SearchEntriesOptions = {
-    page?: number;
-    limit?: number;
-    query?: string;
+import { BaseRequestParameters, Entry, SerializedData, StarlightListResponse } from '../../types';
+/**
+ * Request parameters for searching entries.
+ *
+ * Used by {@apilink SearchSelector.entries}.
+ *
+ * @group Request Parameters
+ */
+export interface SearchEntriesParams extends BaseRequestParameters {
+    /**
+     * A comma-separated list of models. Only entries in these models
+     * will be returned. If undefined, entries from all
+     * workspace models will be listed.
+     *
+     * For instance, to show only entries in the "posts" and "videos" categories,
+     * pass `'posts,videos'`.
+     */
     models?: string;
+    /**
+     * A comma-separated list of categories. Only entries in these categories
+     * will be returned. If undefined, all entries will be listed, independently
+     * of their categories.
+     *
+     * For instance, to show only entries in the "news" and "articles" categories,
+     * pass `'news,category'`.
+     */
     categories?: string;
+    /**
+     * Define how items will be ordered. Check this field type to see the
+     * allowed options.
+     */
     order?: 'title:asc' | 'title:desc' | 'published_at:asc' | 'published_at:desc' | 'updated_at:asc' | 'updated_at:desc';
+    /**
+     * If defined, removes the given item from the list. Useful to create "related
+     * posts" lists.
+     *
+     * Note: this field only accepts IDs, and not slugs. Only one ID is allowed.
+     */
     except?: number;
-};
+}
+/**
+ * A Selector that provide methods to search for content. Only entry search
+ * is supported for the time being.
+ *
+ * You can use a SearchSelector by accessing
+ * {@apilink StarlightClient.search}.
+ *
+ * @group Selectors
+ */
 export interface SearchSelector {
-    entries<T extends SerializedData = Record<string, unknown>>(options?: SearchEntriesOptions): Promise<StarlightListResponse<Entry<T>>>;
+    /**
+     * Returns a {@link StarlightListResponse} with a list of
+     * {@apilink Entry | Entries}. By default, entries from all models are
+     * returned, but filtering by model can be configured.
+     *
+     * @example Listing all entries in all workspace models.
+     * ```ts
+     * import Starlight from '@starlightcms/js-sdk'
+     *
+     * const response = await Starlight.search.entries()
+     * ```
+     *
+     * @example Searching for "hello world" within all entries in all workspace models.
+     * ```ts
+     * import Starlight from '@starlightcms/js-sdk'
+     *
+     * const response = await Starlight.search.entries({
+     *   query: 'hello world'
+     * })
+     * ```
+     *
+     * @example Filtering the last example within specific models.
+     * ```ts
+     * import Starlight from '@starlightcms/js-sdk'
+     *
+     * const response = await Starlight.search.entries({
+     *   query: 'hello world',
+     *   models: 'posts,videos,magazines'
+     * })
+     * ```
+     *
+     * @param options An optional object of request parameters. See
+     * {@link SearchEntriesParams} for all available options.
+     */
+    entries<T extends SerializedData = Record<string, unknown>>(options?: SearchEntriesParams): Promise<StarlightListResponse<Entry<T>>>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/cjs/selectors/Search/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/selectors/Search/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAE1E,oBAAY,oBAAoB,GAAG;IACjC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EACF,WAAW,GACX,YAAY,GACZ,kBAAkB,GAClB,mBAAmB,GACnB,gBAAgB,GAChB,iBAAiB,CAAA;IACrB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,CAAC,SAAS,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxD,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;CAC5C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/selectors/Search/types.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,KAAK,EACL,cAAc,EACd,qBAAqB,EACtB,MAAM,aAAa,CAAA;AAEpB;;;;;;GAMG;AACH,MAAM,WAAW,mBAAoB,SAAQ,qBAAqB;IAChE;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,KAAK,CAAC,EACF,WAAW,GACX,YAAY,GACZ,kBAAkB,GAClB,mBAAmB,GACnB,gBAAgB,GAChB,iBAAiB,CAAA;IACrB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,OAAO,CAAC,CAAC,SAAS,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxD,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;CAC5C"}

package/dist/cjs/selectors/Search/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/selectors/Search/types.ts"],"names":[],"mappings":"","sourcesContent":["import { Entry, SerializedData, StarlightListResponse } from '../../types'\n\nexport type SearchEntriesOptions = {\n  page?: number\n  limit?: number\n  query?: string\n  models?: string\n  categories?: string\n  order?:\n    | 'title:asc'\n    | 'title:desc'\n    | 'published_at:asc'\n    | 'published_at:desc'\n    | 'updated_at:asc'\n    | 'updated_at:desc'\n  except?: number\n}\n\nexport interface SearchSelector {\n  entries<T extends SerializedData = Record<string, unknown>>(\n    options?: SearchEntriesOptions\n  ): Promise<StarlightListResponse<Entry<T>>>\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/selectors/Search/types.ts"],"names":[],"mappings":"","sourcesContent":["import {\n  BaseRequestParameters,\n  Entry,\n  SerializedData,\n  StarlightListResponse,\n} from '../../types'\n\n/**\n * Request parameters for searching entries.\n *\n * Used by {@apilink SearchSelector.entries}.\n *\n * @group Request Parameters\n */\nexport interface SearchEntriesParams extends BaseRequestParameters {\n  /**\n   * A comma-separated list of models. Only entries in these models\n   * will be returned. If undefined, entries from all\n   * workspace models will be listed.\n   *\n   * For instance, to show only entries in the \"posts\" and \"videos\" categories,\n   * pass `'posts,videos'`.\n   */\n  models?: string\n  /**\n   * A comma-separated list of categories. Only entries in these categories\n   * will be returned. If undefined, all entries will be listed, independently\n   * of their categories.\n   *\n   * For instance, to show only entries in the \"news\" and \"articles\" categories,\n   * pass `'news,category'`.\n   */\n  categories?: string\n  /**\n   * Define how items will be ordered. Check this field type to see the\n   * allowed options.\n   */\n  order?:\n    | 'title:asc'\n    | 'title:desc'\n    | 'published_at:asc'\n    | 'published_at:desc'\n    | 'updated_at:asc'\n    | 'updated_at:desc'\n  /**\n   * If defined, removes the given item from the list. Useful to create \"related\n   * posts\" lists.\n   *\n   * Note: this field only accepts IDs, and not slugs. Only one ID is allowed.\n   */\n  except?: number\n}\n\n/**\n * A Selector that provide methods to search for content. Only entry search\n * is supported for the time being.\n *\n * You can use a SearchSelector by accessing\n * {@apilink StarlightClient.search}.\n *\n * @group Selectors\n */\nexport interface SearchSelector {\n  /**\n   * Returns a {@link StarlightListResponse} with a list of\n   * {@apilink Entry | Entries}. By default, entries from all models are\n   * returned, but filtering by model can be configured.\n   *\n   * @example Listing all entries in all workspace models.\n   * ```ts\n   * import Starlight from '@starlightcms/js-sdk'\n   *\n   * const response = await Starlight.search.entries()\n   * ```\n   *\n   * @example Searching for \"hello world\" within all entries in all workspace models.\n   * ```ts\n   * import Starlight from '@starlightcms/js-sdk'\n   *\n   * const response = await Starlight.search.entries({\n   *   query: 'hello world'\n   * })\n   * ```\n   *\n   * @example Filtering the last example within specific models.\n   * ```ts\n   * import Starlight from '@starlightcms/js-sdk'\n   *\n   * const response = await Starlight.search.entries({\n   *   query: 'hello world',\n   *   models: 'posts,videos,magazines'\n   * })\n   * ```\n   *\n   * @param options An optional object of request parameters. See\n   * {@link SearchEntriesParams} for all available options.\n   */\n  entries<T extends SerializedData = Record<string, unknown>>(\n    options?: SearchEntriesParams\n  ): Promise<StarlightListResponse<Entry<T>>>\n}\n"]}

package/dist/cjs/selectors/Singleton/types.d.ts

@@ -1,6 +1,55 @@
 import { SerializedData, Singleton, StarlightItemResponse, StarlightListResponse } from '../../types';
+/**
+ * A Selector that provide methods to list and request information on
+ * {@apilink Singleton | Singletons}.
+ *
+ * You can use an SingletonSelector by accessing
+ * {@apilink ModelInstance.singletons}.
+ *
+ * @group Selectors
+ */
 export interface SingletonSelector {
+    /**
+     * Returns a {@link StarlightItemResponse} with a single {@link Singleton}.
+     * This methods supports typing the returned Singleton by passing its data
+     * type as the generic type `<D>`.
+     *
+     * @example Requesting information from a singleton of slug "home".
+     * ```ts
+     * import Starlight from '@starlightcms/js-sdk'
+     *
+     * const response = await Starlight.singletons.get('home')
+     * ```
+     *
+     * @example Typing last example's response.
+     * ```ts
+     * import Starlight, { StringField, MediaField, VisualField } from '@starlightcms/js-sdk'
+     *
+     * type HomeFields = {
+     *   title: StringField
+     *   subtitle: StringField
+     *   hero_image: MediaField
+     *   hero_content: VisualField
+     * }
+     *
+     * // `response.data` will be of type Singleton<HomeFields>
+     * const response = await Starlight.singletons.get<HomeFields>('home')
+     * ```
+     * @typeParam D - The type of the returned Singleton's `data` property.
+     * @param slug The singleton slug.
+     */
     get<D extends SerializedData>(slug: string): Promise<StarlightItemResponse<Singleton<D>>>;
+    /**
+     * Returns a {@link StarlightListResponse} with a list of
+     * {@apilink Singleton | Singletons}.
+     *
+     * @example Requesting all workspace singletons.
+     * ```ts
+     * import Starlight from '@starlightcms/js-sdk'
+     *
+     * const response = await Starlight.singletons.list()
+     * ```
+     */
     list(): Promise<StarlightListResponse<Singleton<Record<string, unknown>>>>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/cjs/selectors/Singleton/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/selectors/Singleton/types.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,SAAS,EACT,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,aAAa,CAAA;AAEpB,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,CAAC,SAAS,cAAc,EAC1B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC/C,IAAI,IAAI,OAAO,CAAC,qBAAqB,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;CAC3E"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/selectors/Singleton/types.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,SAAS,EACT,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,aAAa,CAAA;AAEpB;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,GAAG,CAAC,CAAC,SAAS,cAAc,EAC1B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAE/C;;;;;;;;;;OAUG;IACH,IAAI,IAAI,OAAO,CAAC,qBAAqB,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;CAC3E"}

package/dist/cjs/selectors/Singleton/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/selectors/Singleton/types.ts"],"names":[],"mappings":"","sourcesContent":["import {\n  SerializedData,\n  Singleton,\n  StarlightItemResponse,\n  StarlightListResponse,\n} from '../../types'\n\nexport interface SingletonSelector {\n  get<D extends SerializedData>(\n    slug: string\n  ): Promise<StarlightItemResponse<Singleton<D>>>\n  list(): Promise<StarlightListResponse<Singleton<Record<string, unknown>>>>\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/selectors/Singleton/types.ts"],"names":[],"mappings":"","sourcesContent":["import {\n  SerializedData,\n  Singleton,\n  StarlightItemResponse,\n  StarlightListResponse,\n} from '../../types'\n\n/**\n * A Selector that provide methods to list and request information on\n * {@apilink Singleton | Singletons}.\n *\n * You can use an SingletonSelector by accessing\n * {@apilink ModelInstance.singletons}.\n *\n * @group Selectors\n */\nexport interface SingletonSelector {\n  /**\n   * Returns a {@link StarlightItemResponse} with a single {@link Singleton}.\n   * This methods supports typing the returned Singleton by passing its data\n   * type as the generic type `<D>`.\n   *\n   * @example Requesting information from a singleton of slug \"home\".\n   * ```ts\n   * import Starlight from '@starlightcms/js-sdk'\n   *\n   * const response = await Starlight.singletons.get('home')\n   * ```\n   *\n   * @example Typing last example's response.\n   * ```ts\n   * import Starlight, { StringField, MediaField, VisualField } from '@starlightcms/js-sdk'\n   *\n   * type HomeFields = {\n   *   title: StringField\n   *   subtitle: StringField\n   *   hero_image: MediaField\n   *   hero_content: VisualField\n   * }\n   *\n   * // `response.data` will be of type Singleton<HomeFields>\n   * const response = await Starlight.singletons.get<HomeFields>('home')\n   * ```\n   * @typeParam D - The type of the returned Singleton's `data` property.\n   * @param slug The singleton slug.\n   */\n  get<D extends SerializedData>(\n    slug: string\n  ): Promise<StarlightItemResponse<Singleton<D>>>\n\n  /**\n   * Returns a {@link StarlightListResponse} with a list of\n   * {@apilink Singleton | Singletons}.\n   *\n   * @example Requesting all workspace singletons.\n   * ```ts\n   * import Starlight from '@starlightcms/js-sdk'\n   *\n   * const response = await Starlight.singletons.list()\n   * ```\n   */\n  list(): Promise<StarlightListResponse<Singleton<Record<string, unknown>>>>\n}\n"]}

package/dist/cjs/types/entities.d.ts

@@ -45,7 +45,8 @@ export interface MediaObject extends StarlightEntity {
     description?: string;
 }
 /**
- * Represents an Author entity returned by the API.
+ * Represents an Author entity returned by the API. Authors are returned in
+ * {@link Entry} requests.
  *
  * @group API Entities
  */
@@ -64,20 +65,97 @@ export interface Model extends StarlightEntity {
     entry_count?: number;
 }
 /**
- * Represents content data returned by either an Entry or
- * Singleton entity from the API.
+ * Represents content data returned by either an {@link Entry} or
+ * {@link 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.
+ *
+ * @category Internal Types
  */
 export declare type SerializedData = Record<string, unknown> | undefined;
 /**
  * Utility type that creates a string map of all fields of the given
- * SerializedData type with the `field` suffix. This is only useful to create
- * request methods that support field querying using the "field:foo" syntax.
+ * SerializedData type with the `field:` prefix. This syntax allows to filter
+ * specific fields when listing {@apilink Entry | Entries}:
  *
- * @internal
+ * - 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:
+ *
+ * ```ts
+ * 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 {@link SerializedData}-like structure, like an object.
+ * For instance, for an {@link Entry} with fields "content" and "summary",
+ * the generated type would look like this:
+ *
+ * ```ts
+ * type GeneratedType = {
+ *   'field:content'?: string
+ *   'field:summary'?: string
+ * }
+ * ```
+ *
+ * However, note that QueryableFields receive a {@link SerializedData}, not an
+ * {@link Entry}:
+ *
+ * ```ts
+ * 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.
+ *
+ * @category Internal Types
  */
-export declare type ModelFieldOptions<D extends SerializedData> = {
-    [K in keyof D as `field:${string & K}`]?: string;
+export declare type QueryableFields<D extends SerializedData> = {
+    [K in keyof D as `field:${string & K}`]?: string | boolean;
 };
+/**
+ * Utility type that return {@link QueryableFields} if the given type T
+ * is an {@link Entry} or a {@link Singleton}, but generates an empty object
+ * otherwise.
+ *
+ * Fun fact: internally, Entries and Singletons have parent Models,
+ * which is why they are called "modelables" here.
+ *
+ * @category Internal Types
+ */
+export declare type WithQueryableFieldsOnModelables<T> = T extends Entry<never> | Singleton<never> ? QueryableFields<Pick<T, 'data'>> : Record<string, never>;
 /**
  * Represents an Entry entity returned by the API.
  *
@@ -196,6 +274,9 @@ export declare type CollectionTypeMapper<T extends CollectionEntityTypes> = T ex
 /**
  * Represents a Collection entity returned by the API.
  *
+ * You can request collections using a {@link CollectionInstance} or a
+ * {@link CollectionSelector}.
+ *
  * @group API Entities
  */
 export interface Collection<T extends CollectionTypes = string> extends StarlightEntity {

package/dist/cjs/types/entities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../../src/types/entities.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../../src/types/entities.ts"],"names":[],"mappings":"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"}

package/dist/cjs/types/entities.js.map

@@ -1 +1 @@
-{"version":3,"file":"entities.js","sourceRoot":"","sources":["../../../src/types/entities.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Base interface used by all entities returned by the API.\n *\n * @internal\n */\ninterface StarlightEntity {\n  id: number\n  created_at: string\n  updated_at?: string\n}\n\n/**\n * Represents a Model Category entity returned by the API.\n *\n * @group API Entities\n */\nexport interface ModelCategory extends StarlightEntity {\n  title: string\n  slug: string\n  entry_count?: number\n}\n\n/**\n * Represents a Media File entity returned by the API.\n *\n * @group API Entities\n */\nexport interface MediaFile extends StarlightEntity {\n  variation: string\n  path: string\n  mime: string\n  background_color?: string\n  filesize: number\n  meta?: Record<string, unknown>\n}\n\n/**\n * Represents a Media Object entity returned by the API.\n *\n * @group API Entities\n */\nexport interface MediaObject extends StarlightEntity {\n  name: string\n  extension: string\n  mime: string\n  files: MediaFile[]\n  alt?: string\n  description?: string\n}\n\n/**\n * Represents an Author entity returned by the API.\n *\n * @group API Entities\n */\nexport interface Author {\n  id: number\n  name: string\n}\n\n/**\n * Represents a Model entity returned by the API.\n *\n * @group API Entities\n */\nexport interface Model extends StarlightEntity {\n  title: string\n  slug: string\n  entry_count?: number\n}\n\n/**\n * Represents content data returned by either an Entry or\n * Singleton entity from the API.\n */\nexport type SerializedData = Record<string, unknown> | undefined\n\n/**\n * Utility type that creates a string map of all fields of the given\n * SerializedData type with the `field` suffix. This is only useful to create\n * request methods that support field querying using the \"field:foo\" syntax.\n *\n * @internal\n */\nexport type ModelFieldOptions<D extends SerializedData> = {\n  [K in keyof D as `field:${string & K}`]?: string\n}\n\n/**\n * Represents an Entry entity returned by the API.\n *\n * An Entry's `data` field can be further typed by passing an object-like\n * structure as the D generic type. This is useful to provide type-safety to\n * your application, since the `data` field is a generic JS object by default.\n *\n * It's recommended to use the Field types provided by this SDK to type your\n * entities using a type definition file on your project. For instance:\n *\n * ```ts\n * // starlight.d.ts file\n * import { VisualField, MediaField } from '@starlightcms/js-sdk'\n *\n * type PostFields = {\n *   featured_image: MediaField\n *   content: VisualField\n * }\n *\n * declare module '@starlightcms/js-sdk' {\n *   export interface DefaultModelDefinition {\n *     posts: PostFields\n *   }\n * }\n * ```\n *\n * You can place this type definition file anywhere in your repository, but it's\n * good practice to place it at the same level as your root index.ts file. Then,\n * in your files, all SDK calls will correctly type `posts`:\n *\n * ```ts\n * import Starlight from '@starlightcms/js-sdk'\n *\n * // response type will be StarlightItemResponse<Entry<PostFields>> on request success\n * const response = await Starlight.posts.entries.get('hello-world')\n *\n * // helloWorld type is Entry<PostFields>\n * const helloWorld = response.data\n * ```\n *\n * See {@apilink DefaultModelDefinition} for more info.\n *\n * @group API Entities\n */\nexport interface Entry<D extends SerializedData>\n  extends Omit<StarlightEntity, 'created_at'> {\n  title: string\n  slug: string\n  data: D\n  author: Author\n  model?: Model\n  category: ModelCategory | null\n  published_at: string | null\n}\n\n/**\n * Represents a Singleton entity returned by the API.\n *\n * A Singleton's `data` field can be further typed by passing an object-like\n * structure as the D generic type. This is useful to provide type-safety to\n * your application, since the `data` field is a generic JS object by default.\n *\n * It's recommended to use the Field types provided by this SDK to type your\n * Singletons. For instance:\n *\n * ```ts\n * import { StringField, VisualField, MediaField } from '@starlightcms/js-sdk'\n *\n * type HomeFields = {\n *   site_title: StringField\n *   hero_image: MediaField\n *   hero_content: VisualField\n * }\n *\n * // response type will be StarlightItemResponse<Singleton<HomeFields>> on request success\n * const response = Starlight.singletons.get<HomeFields>('home')\n *\n * // home type is Singleton<HomeFields>\n * const home = response.data\n * ```\n *\n * You could also place all your Singleton field types in the same type\n * definition file used to configure Entry fields, which makes it easier to\n * import these types in other files on your project. See\n * {@apilink DefaultModelDefinition} for more info.\n *\n * @group API Entities\n */\nexport interface Singleton<D extends SerializedData>\n  extends Omit<StarlightEntity, 'created_at'> {\n  title: string\n  slug: string\n  data: D\n  published_at: string | null\n}\n\n/**\n * Currently supported Collection types. This type is mainly used to provide\n * autocompletion on IDEs, since it lets users use any string as well as the\n * known supported types.\n *\n * @internal\n */\nexport type CollectionTypes = 'entry' | 'singleton' | 'media' | string\n\n/**\n * Currently supported Collection entities. This type is mainly used to infer\n * the collection type string (see {@link CollectionTypes}) from the type of\n * entity that that Collection holds.\n *\n * @internal\n */\nexport type CollectionEntityTypes =\n  | Entry<never>\n  | Singleton<never>\n  | MediaObject\n  | unknown\n\n/**\n * Infers a Collection type from an entity type. See {@link CollectionTypes} and\n * {@link CollectionEntityTypes} to know more.\n *\n * @internal\n */\nexport type CollectionTypeMapper<T extends CollectionEntityTypes> =\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  T extends Entry<any>\n    ? 'entry'\n    : T extends Singleton<any> // eslint-disable-line @typescript-eslint/no-explicit-any\n    ? 'singleton'\n    : T extends MediaObject\n    ? 'media'\n    : string\n\n/**\n * Represents a Collection entity returned by the API.\n *\n * @group API Entities\n */\nexport interface Collection<T extends CollectionTypes = string>\n  extends StarlightEntity {\n  title: string\n  slug: string\n  type: T\n  item_count?: number\n}\n\n/**\n * Currently supported Relation types.\n */\ntype RelationTypes =\n  | Entry<never>\n  | Singleton<never>\n  | MediaObject\n  | Collection\n  | unknown\n\n/**\n * Represents a Relation entity returned by the API.\n *\n * @group API Entities\n */\nexport interface Relation<T extends RelationTypes> {\n  /**\n   * The relation type, which is always a string. If the `object` field of this\n   * Relation is an Entry, type will be `entry`, if it's a Singleton, type will\n   * be `singleton`, and so on.\n   */\n  type: T extends Entry<never>\n    ? 'entry'\n    : T extends Singleton<never>\n    ? 'singleton'\n    : T extends MediaObject\n    ? 'media'\n    : T extends Collection\n    ? 'collection'\n    : string\n  id: number\n  object: T\n}\n"]}
+{"version":3,"file":"entities.js","sourceRoot":"","sources":["../../../src/types/entities.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Base interface used by all entities returned by the API.\n *\n * @internal\n */\ninterface StarlightEntity {\n  id: number\n  created_at: string\n  updated_at?: string\n}\n\n/**\n * Represents a Model Category entity returned by the API.\n *\n * @group API Entities\n */\nexport interface ModelCategory extends StarlightEntity {\n  title: string\n  slug: string\n  entry_count?: number\n}\n\n/**\n * Represents a Media File entity returned by the API.\n *\n * @group API Entities\n */\nexport interface MediaFile extends StarlightEntity {\n  variation: string\n  path: string\n  mime: string\n  background_color?: string\n  filesize: number\n  meta?: Record<string, unknown>\n}\n\n/**\n * Represents a Media Object entity returned by the API.\n *\n * @group API Entities\n */\nexport interface MediaObject extends StarlightEntity {\n  name: string\n  extension: string\n  mime: string\n  files: MediaFile[]\n  alt?: string\n  description?: string\n}\n\n/**\n * Represents an Author entity returned by the API. Authors are returned in\n * {@link Entry} requests.\n *\n * @group API Entities\n */\nexport interface Author {\n  id: number\n  name: string\n}\n\n/**\n * Represents a Model entity returned by the API.\n *\n * @group API Entities\n */\nexport interface Model extends StarlightEntity {\n  title: string\n  slug: string\n  entry_count?: number\n}\n\n/**\n * Represents content data returned by either an {@link Entry} or\n * {@link Singleton} entity from the API.\n *\n * This is a utility type used internally by the SDK and you don't\n * need to use it. Its purpose is to constraint Entry and Singleton\n * data to the shape of a JS object.\n *\n * @category Internal Types\n */\nexport type SerializedData = Record<string, unknown> | undefined\n\n/**\n * Utility type that creates a string map of all fields of the given\n * SerializedData type with the `field:` prefix. This syntax allows to filter\n * specific fields when listing {@apilink Entry | Entries}:\n *\n * - Text fields can be filtered by a string query. This works just like\n *   passing a `query` parameter, but it only applies to one field.\n * - Boolean fields can be filtered by \"true\" or \"false\".\n *\n * If a request uses this type, it means that this syntax can be used in their\n * parameters:\n *\n * ```ts\n * import Starlight from '@starlightcms/js-sdk'\n *\n * const response = await Starlight.posts.entries.list({\n *   // EntrySelector.list() supports the \"field:foo\" syntax:\n *   'field:content': 'hello world',\n *   'field:is_featured': true,\n *\n *   // EntrySelector.list() also support other parameters,\n *   // which are passed in this object too:\n *   page: 42,\n *   limit: 20,\n * })\n * ```\n *\n * @remark\n *\n * The information below is only useful for SDK maintainers.\n *\n * This type receives a {@link SerializedData}-like structure, like an object.\n * For instance, for an {@link Entry} with fields \"content\" and \"summary\",\n * the generated type would look like this:\n *\n * ```ts\n * type GeneratedType = {\n *   'field:content'?: string\n *   'field:summary'?: string\n * }\n * ```\n *\n * However, note that QueryableFields receive a {@link SerializedData}, not an\n * {@link Entry}:\n *\n * ```ts\n * import { VisualField, StringField } from '@starlightcms/js-sdk'\n *\n * type EntryFields = {\n *   content: VisualField\n *   summary: StringField\n * }\n *\n * type MyEntry = Entry<EntryFields>\n *\n * // Error TS2344: Type does not satisfy the constraint 'SerializedData'\n * type GeneratedType = QueryableFields<MyEntry>\n *\n * // Works!\n * type GeneratedType = QueryableFields<EntryFields>\n * ```\n *\n * This type is only useful to request methods that support\n * field querying using the \"field:foo\" syntax.\n *\n * @category Internal Types\n */\nexport type QueryableFields<D extends SerializedData> = {\n  [K in keyof D as `field:${string & K}`]?: string | boolean\n}\n\n/**\n * Utility type that return {@link QueryableFields} if the given type T\n * is an {@link Entry} or a {@link Singleton}, but generates an empty object\n * otherwise.\n *\n * Fun fact: internally, Entries and Singletons have parent Models,\n * which is why they are called \"modelables\" here.\n *\n * @category Internal Types\n */\nexport type WithQueryableFieldsOnModelables<T> = T extends\n  | Entry<never>\n  | Singleton<never>\n  ? QueryableFields<Pick<T, 'data'>>\n  : Record<string, never>\n\n/**\n * Represents an Entry entity returned by the API.\n *\n * An Entry's `data` field can be further typed by passing an object-like\n * structure as the D generic type. This is useful to provide type-safety to\n * your application, since the `data` field is a generic JS object by default.\n *\n * It's recommended to use the Field types provided by this SDK to type your\n * entities using a type definition file on your project. For instance:\n *\n * ```ts\n * // starlight.d.ts file\n * import { VisualField, MediaField } from '@starlightcms/js-sdk'\n *\n * type PostFields = {\n *   featured_image: MediaField\n *   content: VisualField\n * }\n *\n * declare module '@starlightcms/js-sdk' {\n *   export interface DefaultModelDefinition {\n *     posts: PostFields\n *   }\n * }\n * ```\n *\n * You can place this type definition file anywhere in your repository, but it's\n * good practice to place it at the same level as your root index.ts file. Then,\n * in your files, all SDK calls will correctly type `posts`:\n *\n * ```ts\n * import Starlight from '@starlightcms/js-sdk'\n *\n * // response type will be StarlightItemResponse<Entry<PostFields>> on request success\n * const response = await Starlight.posts.entries.get('hello-world')\n *\n * // helloWorld type is Entry<PostFields>\n * const helloWorld = response.data\n * ```\n *\n * See {@apilink DefaultModelDefinition} for more info.\n *\n * @group API Entities\n */\nexport interface Entry<D extends SerializedData>\n  extends Omit<StarlightEntity, 'created_at'> {\n  title: string\n  slug: string\n  data: D\n  author: Author\n  model?: Model\n  category: ModelCategory | null\n  published_at: string | null\n}\n\n/**\n * Represents a Singleton entity returned by the API.\n *\n * A Singleton's `data` field can be further typed by passing an object-like\n * structure as the D generic type. This is useful to provide type-safety to\n * your application, since the `data` field is a generic JS object by default.\n *\n * It's recommended to use the Field types provided by this SDK to type your\n * Singletons. For instance:\n *\n * ```ts\n * import { StringField, VisualField, MediaField } from '@starlightcms/js-sdk'\n *\n * type HomeFields = {\n *   site_title: StringField\n *   hero_image: MediaField\n *   hero_content: VisualField\n * }\n *\n * // response type will be StarlightItemResponse<Singleton<HomeFields>> on request success\n * const response = Starlight.singletons.get<HomeFields>('home')\n *\n * // home type is Singleton<HomeFields>\n * const home = response.data\n * ```\n *\n * You could also place all your Singleton field types in the same type\n * definition file used to configure Entry fields, which makes it easier to\n * import these types in other files on your project. See\n * {@apilink DefaultModelDefinition} for more info.\n *\n * @group API Entities\n */\nexport interface Singleton<D extends SerializedData>\n  extends Omit<StarlightEntity, 'created_at'> {\n  title: string\n  slug: string\n  data: D\n  published_at: string | null\n}\n\n/**\n * Currently supported Collection types. This type is mainly used to provide\n * autocompletion on IDEs, since it lets users use any string as well as the\n * known supported types.\n *\n * @internal\n */\nexport type CollectionTypes = 'entry' | 'singleton' | 'media' | string\n\n/**\n * Currently supported Collection entities. This type is mainly used to infer\n * the collection type string (see {@link CollectionTypes}) from the type of\n * entity that that Collection holds.\n *\n * @internal\n */\nexport type CollectionEntityTypes =\n  | Entry<never>\n  | Singleton<never>\n  | MediaObject\n  | unknown\n\n/**\n * Infers a Collection type from an entity type. See {@link CollectionTypes} and\n * {@link CollectionEntityTypes} to know more.\n *\n * @internal\n */\nexport type CollectionTypeMapper<T extends CollectionEntityTypes> =\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  T extends Entry<any>\n    ? 'entry'\n    : T extends Singleton<any> // eslint-disable-line @typescript-eslint/no-explicit-any\n    ? 'singleton'\n    : T extends MediaObject\n    ? 'media'\n    : string\n\n/**\n * Represents a Collection entity returned by the API.\n *\n * You can request collections using a {@link CollectionInstance} or a\n * {@link CollectionSelector}.\n *\n * @group API Entities\n */\nexport interface Collection<T extends CollectionTypes = string>\n  extends StarlightEntity {\n  title: string\n  slug: string\n  type: T\n  item_count?: number\n}\n\n/**\n * Currently supported Relation types.\n */\ntype RelationTypes =\n  | Entry<never>\n  | Singleton<never>\n  | MediaObject\n  | Collection\n  | unknown\n\n/**\n * Represents a Relation entity returned by the API.\n *\n * @group API Entities\n */\nexport interface Relation<T extends RelationTypes> {\n  /**\n   * The relation type, which is always a string. If the `object` field of this\n   * Relation is an Entry, type will be `entry`, if it's a Singleton, type will\n   * be `singleton`, and so on.\n   */\n  type: T extends Entry<never>\n    ? 'entry'\n    : T extends Singleton<never>\n    ? 'singleton'\n    : T extends MediaObject\n    ? 'media'\n    : T extends Collection\n    ? 'collection'\n    : string\n  id: number\n  object: T\n}\n"]}

package/dist/cjs/types/index.d.ts

@@ -14,14 +14,36 @@ export * from './selectors';
 /**
  * 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.
  */
 export declare type BaseUrl = 'https://query.starlight.sh/v2' | string;
 /**
+ * The available options to configure a {@link StarlightClient}.
+ *
+ * `workspace` is required when creating new clients or configuring the
+ * {@apilink default | default client}.
  * @group Client
  */
 export declare type StarlightConfig = {
+    /**
+     * 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.
+     */
     workspace?: string;
+    /**
+     * 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.
+     */
     baseUrl?: BaseUrl;
+    /**
+     * When true, logs all API requests in the console. Defaults to false.
+     */
     debug?: boolean;
 };
 /**
@@ -66,10 +88,11 @@ export interface StarlightClient<D extends WorkspaceModelDefinition = DefaultMod
      * const rootElement = document.getElementById("root")
      * const root = createRoot(rootElement)
      *
-     * root.render(<App />)
+     * root.render(<MyApp />)
      * ```
      *
-     * @param config A configuration object. Required.
+     * @param config A configuration object. See {@link StarlightConfig} to view
+     * all available options.
      * @category Other Methods
      */
     configure(config: StarlightConfig): void;
@@ -93,7 +116,7 @@ export interface StarlightClient<D extends WorkspaceModelDefinition = DefaultMod
      */
     getBaseUrl(): string;
     /**
-     * Returns a Promise that results in a response or throws an StarlightError.
+     * Returns a Promise that results in a response or throws a StarlightError.
      * The response will be the parsed JSON data sent by the API.
      *
      * This method is used internally by all Selectors and Instances to request
@@ -120,7 +143,7 @@ export interface StarlightClient<D extends WorkspaceModelDefinition = DefaultMod
     get<T = Record<string, unknown>>(path: string, params?: Record<string, string | number | boolean | undefined>, options?: RequestInit): Promise<T>;
     /**
      * Returns a {@link DynamicModelSelector}, which is a {@link ModelSelector}
-     * with support for creating {@link ModelInstance}s using the dynamic syntax.
+     * with support for creating {@apilink ModelInstance | ModelInstances} using the dynamic syntax.
      *
      * This is an accessor, which means that it should be used just like a common
      * object parameter. For instance:
@@ -139,7 +162,7 @@ export interface StarlightClient<D extends WorkspaceModelDefinition = DefaultMod
     /**
      * Returns a {@link DynamicModelInstance}, which is a
      * {@link ModelInstance} with support for creating
-     * {@link ModelCategoryInstance}s using the dynamic syntax. For instance:
+     * {@apilink ModelCategoryInstance | ModelCategoryInstances} using the dynamic syntax. For instance:
      *
      * ```ts
      * import Starlight from '@starlightcms/js-sdk'
@@ -172,7 +195,7 @@ export interface StarlightClient<D extends WorkspaceModelDefinition = DefaultMod
     /**
      * Returns a {@link DynamicCollectionSelector}, which is a
      * {@link CollectionSelector} with support for creating
-     * {@link CollectionInstance}s using the dynamic syntax.
+     * {@apilink CollectionInstance | CollectionInstances} using the dynamic syntax.
      *
      * This is an accessor, which means that it should be used just like a common
      * object parameter. For instance:
@@ -199,6 +222,16 @@ export interface StarlightClient<D extends WorkspaceModelDefinition = DefaultMod
      *
      * See {@link CollectionInstance} for more info.
      *
+     * @example Typing the returned CollectionInstance.
+     * ```ts
+     * import Starlight, { MediaObject } from '@starlightcms/js-sdk'
+     *
+     * const response = await Starlight.collection<MediaObject>('carousel-images').items()
+     * ```
+     *
+     * @typeParam T - The type of entity this Collection holds. You can pass this
+     * type parameter to correctly type the response of the
+     * {@apilink CollectionInstance.items} method.
      * @category Instance Methods
      */
     collection<T extends CollectionEntityTypes>(slug: string | number): CollectionInstance<T>;
@@ -239,8 +272,12 @@ export interface StarlightClient<D extends WorkspaceModelDefinition = DefaultMod
 }
 /**
  * This type adds support for the dynamic syntax to the StarlightClient
- * interface, which allows users to create {@link ModelInstance}s dynamically.
- * See {@link StarlightClient} to learn which methods it provides.
+ * interface, which allows users to create
+ * {@apilink DynamicModelInstance| DynamicModelInstances} dynamically.
+ * See {@link StarlightClient} to learn which methods it provides. Also see
+ * {@doclink requests-and-responses#dynamic-syntax | 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
@@ -469,4 +506,57 @@ export interface DefaultModelDefinition extends WorkspaceModelDefinition {
 export interface WorkspaceModelDefinition {
     [slug: string]: SerializedData;
 }
+/**
+ * Request parameters used by most SDK `list()` methods.
+ *
+ * @group Request Parameters
+ */
+export interface BaseRequestParameters {
+    /**
+     * The page requested.
+     */
+    page?: number;
+    /**
+     * The limit of items per page.
+     */
+    limit?: number;
+    /**
+     * A search query string.
+     *
+     * For instance, searching for "out" will match both "check out!" and
+     * "about us". Search is not case-sensitive.
+     */
+    query?: string;
+}
+/**
+ * Request parameters used by most SDK methods that support advanced querying.
+ *
+ * @group Request Parameters
+ */
+export interface QueryableRequestParameters {
+    /**
+     * A search query string that matches a specific word within boundaries.
+     * Search is not case-sensitive.
+     *
+     * For instance, searching for "phone" will match "This is my phone!"
+     * but won't match "This is my telephone!".
+     */
+    'query:word'?: string;
+    /**
+     * A comma-separated list of fields to look up on when searching using
+     * `query` or `query:word`. If undefined, all text fields will be searched on,
+     * including Visual Editor fields. Search is not case-sensitive.
+     *
+     * For instance, to limit search on the "content" and "summary" fields of a
+     * model, pass `'content,summary'`.
+     */
+    fields?: string;
+    /**
+     * If defined, removes the given item from the list. Useful to create "related
+     * posts" lists.
+     *
+     * Note: this field only accepts IDs, and not slugs. Only one ID is allowed.
+     */
+    except?: number;
+}
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"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"}