@starlightcms/js-sdk 0.9.0 → 0.11.0

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

@@ -1,13 +1,28 @@
+/**
+ * Base interface used by all entities returned by the API.
+ *
+ * @internal
+ */
 interface StarlightEntity {
     id: number;
     created_at: string;
     updated_at?: string;
 }
+/**
+ * Represents a Model Category entity returned by the API.
+ *
+ * @group API Entities
+ */
 export interface ModelCategory extends StarlightEntity {
     title: string;
     slug: string;
     entry_count?: number;
 }
+/**
+ * Represents a Media File entity returned by the API.
+ *
+ * @group API Entities
+ */
 export interface MediaFile extends StarlightEntity {
     variation: string;
     path: string;
@@ -16,6 +31,11 @@ export interface MediaFile extends StarlightEntity {
     filesize: number;
     meta?: Record<string, unknown>;
 }
+/**
+ * Represents a Media Object entity returned by the API.
+ *
+ * @group API Entities
+ */
 export interface MediaObject extends StarlightEntity {
     name: string;
     extension: string;
@@ -24,19 +44,162 @@ export interface MediaObject extends StarlightEntity {
     alt?: string;
     description?: string;
 }
+/**
+ * Represents an Author entity returned by the API. Authors are returned in
+ * {@link Entry} requests.
+ *
+ * @group API Entities
+ */
 export interface Author {
     id: number;
     name: string;
 }
+/**
+ * Represents a Model entity returned by the API.
+ *
+ * @group API Entities
+ */
 export interface Model extends StarlightEntity {
     title: string;
     slug: string;
     entry_count?: number;
 }
+/**
+ * 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;
-export declare type ModelFieldOptions<D extends SerializedData> = {
-    [K in keyof D as `field:${string & K}`]?: string;
+/**
+ * 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 {@apilink Entry | 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:
+ *
+ * ```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 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.
+ *
+ * An Entry's `data` field can be further typed by passing an object-like
+ * structure as the D generic type. This is useful to provide type-safety to
+ * your application, since the `data` field is a generic JS object by default.
+ *
+ * It's recommended to use the Field types provided by this SDK to type your
+ * entities using a type definition file on your project. For instance:
+ *
+ * ```ts
+ * // starlight.d.ts file
+ * import { VisualField, MediaField } from '@starlightcms/js-sdk'
+ *
+ * type PostFields = {
+ *   featured_image: MediaField
+ *   content: VisualField
+ * }
+ *
+ * declare module '@starlightcms/js-sdk' {
+ *   export interface DefaultModelDefinition {
+ *     posts: PostFields
+ *   }
+ * }
+ * ```
+ *
+ * You can place this type definition file anywhere in your repository, but it's
+ * good practice to place it at the same level as your root index.ts file. Then,
+ * in your files, all SDK calls will correctly type `posts`:
+ *
+ * ```ts
+ * import Starlight from '@starlightcms/js-sdk'
+ *
+ * // response type will be StarlightItemResponse<Entry<PostFields>> on request success
+ * const response = await Starlight.posts.entries.get('hello-world')
+ *
+ * // helloWorld type is Entry<PostFields>
+ * const helloWorld = response.data
+ * ```
+ *
+ * See {@apilink DefaultModelDefinition} for more info.
+ *
+ * @group API Entities
+ */
 export interface Entry<D extends SerializedData> extends Omit<StarlightEntity, 'created_at'> {
     title: string;
     slug: string;
@@ -46,21 +209,97 @@ export interface Entry<D extends SerializedData> extends Omit<StarlightEntity, '
     category: ModelCategory | null;
     published_at: string | null;
 }
+/**
+ * Represents a Singleton entity returned by the API.
+ *
+ * A Singleton's `data` field can be further typed by passing an object-like
+ * structure as the D generic type. This is useful to provide type-safety to
+ * your application, since the `data` field is a generic JS object by default.
+ *
+ * It's recommended to use the Field types provided by this SDK to type your
+ * Singletons. For instance:
+ *
+ * ```ts
+ * import { StringField, VisualField, MediaField } from '@starlightcms/js-sdk'
+ *
+ * type HomeFields = {
+ *   site_title: StringField
+ *   hero_image: MediaField
+ *   hero_content: VisualField
+ * }
+ *
+ * // response type will be StarlightItemResponse<Singleton<HomeFields>> on request success
+ * const response = Starlight.singletons.get<HomeFields>('home')
+ *
+ * // home type is Singleton<HomeFields>
+ * const home = response.data
+ * ```
+ *
+ * You could also place all your Singleton field types in the same type
+ * definition file used to configure Entry fields, which makes it easier to
+ * import these types in other files on your project. See
+ * {@apilink DefaultModelDefinition} for more info.
+ *
+ * @group API Entities
+ */
 export interface Singleton<D extends SerializedData> extends Omit<StarlightEntity, 'created_at'> {
     title: string;
     slug: string;
     data: D;
     published_at: string | null;
 }
+/**
+ * Currently supported Collection types. This type is mainly used to provide
+ * autocompletion on IDEs, since it lets users use any string as well as the
+ * known supported types.
+ *
+ * @internal
+ */
 export declare type CollectionTypes = 'entry' | 'singleton' | 'media' | string;
+/**
+ * Currently supported Collection entities. This type is mainly used to infer
+ * the collection type string (see {@link CollectionTypes}) from the type of
+ * entity that that Collection holds.
+ *
+ * @internal
+ */
+export declare type CollectionEntityTypes = Entry<never> | Singleton<never> | MediaObject | unknown;
+/**
+ * Infers a Collection type from an entity type. See {@link CollectionTypes} and
+ * {@link CollectionEntityTypes} to know more.
+ *
+ * @internal
+ */
+export declare type CollectionTypeMapper<T extends CollectionEntityTypes> = T extends Entry<any> ? 'entry' : T extends Singleton<any> ? 'singleton' : T extends MediaObject ? 'media' : string;
+/**
+ * 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 {
     title: string;
     slug: string;
     type: T;
     item_count?: number;
 }
+/**
+ * Currently supported Relation types.
+ */
 declare type RelationTypes = Entry<never> | Singleton<never> | MediaObject | Collection | unknown;
+/**
+ * Represents a Relation entity returned by the API.
+ *
+ * @group API Entities
+ */
 export interface Relation<T extends RelationTypes> {
+    /**
+     * The relation type, which is always a string. If the `object` field of this
+     * Relation is an Entry, type will be `entry`, if it's a Singleton, type will
+     * be `singleton`, and so on.
+     */
     type: T extends Entry<never> ? 'entry' : T extends Singleton<never> ? 'singleton' : T extends MediaObject ? 'media' : T extends Collection ? 'collection' : string;
     id: number;
     object: T;

package/dist/esm/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/esm/types/entities.js.map

@@ -1 +1 @@
-{"version":3,"file":"entities.js","sourceRoot":"","sources":["../../../src/types/entities.ts"],"names":[],"mappings":"","sourcesContent":["interface StarlightEntity {\n  id: number\n  created_at: string\n  updated_at?: string\n}\n\nexport interface ModelCategory extends StarlightEntity {\n  title: string\n  slug: string\n  entry_count?: number\n}\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\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\nexport interface Author {\n  id: number\n  name: string\n}\n\nexport interface Model extends StarlightEntity {\n  title: string\n  slug: string\n  entry_count?: number\n}\n\nexport type SerializedData = Record<string, unknown> | undefined\n\nexport type ModelFieldOptions<D extends SerializedData> = {\n  [K in keyof D as `field:${string & K}`]?: string\n}\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\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\nexport type CollectionTypes = 'entry' | 'singleton' | 'media' | string\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\ntype RelationTypes =\n  | Entry<never>\n  | Singleton<never>\n  | MediaObject\n  | Collection\n  | unknown\n\nexport interface Relation<T extends RelationTypes> {\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/esm/types/fields.d.ts

@@ -1,10 +1,73 @@
 import { MediaObject, Relation } from './entities';
 import { VisualData } from './visual';
+/**
+ * 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 {@apilink DefaultModelDefinition}
+ * for more info.
+ *
+ * @group Data Fields
+ */
 export declare type BooleanField = boolean;
+/**
+ * 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 {@apilink DefaultModelDefinition}
+ * for more info.
+ *
+ * @group Data Fields
+ */
 export declare type HtmlField = string;
+/**
+ * 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 {@apilink DefaultModelDefinition}
+ * for more info.
+ *
+ * @group Data Fields
+ */
 export declare type MediaField = MediaObject;
+/**
+ * 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 {@apilink DefaultModelDefinition}
+ * for more info.
+ *
+ * @group Data Fields
+ */
 export declare type RelationField<T> = Relation<T>;
+/**
+ * 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 {@apilink DefaultModelDefinition}
+ * for more info.
+ *
+ * @group Data Fields
+ */
 export declare type StringField = 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 {@apilink DefaultModelDefinition}
+ * for more info.
+ *
+ * @group Data Fields
+ */
 export declare type TextField = string;
+/**
+ * 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 {@apilink DefaultModelDefinition}
+ * for more info.
+ *
+ * @group Data Fields
+ */
 export declare type VisualField = VisualData;
 //# sourceMappingURL=fields.d.ts.map

package/dist/esm/types/fields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../../../src/types/fields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAErC,oBAAY,YAAY,GAAG,OAAO,CAAA;AAElC,oBAAY,SAAS,GAAG,MAAM,CAAA;AAE9B,oBAAY,UAAU,GAAG,WAAW,CAAA;AAEpC,oBAAY,aAAa,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAA;AAE1C,oBAAY,WAAW,GAAG,MAAM,CAAA;AAEhC,oBAAY,SAAS,GAAG,MAAM,CAAA;AAE9B,oBAAY,WAAW,GAAG,UAAU,CAAA"}
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../../../src/types/fields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAErC;;;;;;;;GAQG;AACH,oBAAY,YAAY,GAAG,OAAO,CAAA;AAElC;;;;;;;;GAQG;AACH,oBAAY,SAAS,GAAG,MAAM,CAAA;AAE9B;;;;;;;;GAQG;AACH,oBAAY,UAAU,GAAG,WAAW,CAAA;AAEpC;;;;;;;;GAQG;AACH,oBAAY,aAAa,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAA;AAE1C;;;;;;;;GAQG;AACH,oBAAY,WAAW,GAAG,MAAM,CAAA;AAEhC;;;;;;;;GAQG;AACH,oBAAY,SAAS,GAAG,MAAM,CAAA;AAE9B;;;;;;;;GAQG;AACH,oBAAY,WAAW,GAAG,UAAU,CAAA"}

package/dist/esm/types/fields.js.map

@@ -1 +1 @@
-{"version":3,"file":"fields.js","sourceRoot":"","sources":["../../../src/types/fields.ts"],"names":[],"mappings":"","sourcesContent":["import { MediaObject, Relation } from './entities'\nimport { VisualData } from './visual'\n\nexport type BooleanField = boolean\n\nexport type HtmlField = string\n\nexport type MediaField = MediaObject\n\nexport type RelationField<T> = Relation<T>\n\nexport type StringField = string\n\nexport type TextField = string\n\nexport type VisualField = VisualData\n"]}
+{"version":3,"file":"fields.js","sourceRoot":"","sources":["../../../src/types/fields.ts"],"names":[],"mappings":"","sourcesContent":["import { MediaObject, Relation } from './entities'\nimport { VisualData } from './visual'\n\n/**\n * Represents a Boolean Field returned by the API.\n *\n * Field types are used to type Entry and Singleton objects when requesting\n * them using some SDK methods. See {@apilink DefaultModelDefinition}\n * for more info.\n *\n * @group Data Fields\n */\nexport type BooleanField = boolean\n\n/**\n * Represents a HTML Field returned by the API.\n *\n * Field types are used to type Entry and Singleton objects when requesting\n * them using some SDK methods. See {@apilink DefaultModelDefinition}\n * for more info.\n *\n * @group Data Fields\n */\nexport type HtmlField = string\n\n/**\n * Represents a Media Field returned by the API.\n *\n * Field types are used to type Entry and Singleton objects when requesting\n * them using some SDK methods. See {@apilink DefaultModelDefinition}\n * for more info.\n *\n * @group Data Fields\n */\nexport type MediaField = MediaObject\n\n/**\n * Represents a Relation Field returned by the API.\n *\n * Field types are used to type Entry and Singleton objects when requesting\n * them using some SDK methods. See {@apilink DefaultModelDefinition}\n * for more info.\n *\n * @group Data Fields\n */\nexport type RelationField<T> = Relation<T>\n\n/**\n * Represents a String Field returned by the API.\n *\n * Field types are used to type Entry and Singleton objects when requesting\n * them using some SDK methods. See {@apilink DefaultModelDefinition}\n * for more info.\n *\n * @group Data Fields\n */\nexport type StringField = string\n\n/**\n * Represents a Text Field returned by the API.\n *\n * Field types are used to type Entry and Singleton objects when requesting\n * them using some SDK methods. See {@apilink DefaultModelDefinition}\n * for more info.\n *\n * @group Data Fields\n */\nexport type TextField = string\n\n/**\n * Represents a Visual Field returned by the API.\n *\n * Field types are used to type Entry and Singleton objects when requesting\n * them using some SDK methods. See {@apilink DefaultModelDefinition}\n * for more info.\n *\n * @group Data Fields\n */\nexport type VisualField = VisualData\n"]}