@starlightcms/js-sdk 3.2.0 → 4.0.0-beta.1

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

@@ -9,7 +9,7 @@ import { VisualData } from './visual';
  *
  * @group Data Fields
  */
-export type BooleanField = boolean;
+export type BooleanField = boolean | undefined;
 /**
  * Represents an HTML Field returned by the API.
  *
@@ -19,7 +19,7 @@ export type BooleanField = boolean;
  *
  * @group Data Fields
  */
-export type HtmlField = string;
+export type HtmlField = string | undefined;
 /**
  * Represents a Media Field returned by the API.
  *
@@ -29,7 +29,7 @@ export type HtmlField = string;
  *
  * @group Data Fields
  */
-export type MediaField = MediaObject;
+export type MediaField = MediaObject | undefined;
 /**
  * Represents a Relation Field returned by the API.
  *
@@ -39,7 +39,7 @@ export type MediaField = MediaObject;
  *
  * @group Data Fields
  */
-export type RelationField<T> = Relation<T>;
+export type RelationField<T> = Relation<T> | undefined;
 /**
  * Represents a String Field returned by the API.
  *
@@ -49,7 +49,7 @@ export type RelationField<T> = Relation<T>;
  *
  * @group Data Fields
  */
-export type StringField = string;
+export type StringField = string | undefined;
 /**
  * Represents a Text Field returned by the API.
  *
@@ -59,7 +59,7 @@ export type StringField = string;
  *
  * @group Data Fields
  */
-export type TextField = string;
+export type TextField = string | undefined;
 /**
  * Represents a Visual Field returned by the API.
  *
@@ -69,5 +69,5 @@ export type TextField = string;
  *
  * @group Data Fields
  */
-export type VisualField = VisualData;
+export type VisualField = VisualData | undefined;
 //# sourceMappingURL=fields.d.ts.map

package/dist/cjs/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;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,CAAA;AAElC;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAA;AAE9B;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,CAAA;AAEpC;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAA;AAE1C;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAA;AAEhC;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAA;AAE9B;;;;;;;;GAQG;AACH,MAAM,MAAM,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,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,SAAS,CAAA;AAE9C;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,SAAS,CAAA;AAE1C;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,SAAS,CAAA;AAEhD;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,GAAG,SAAS,CAAA;AAEtD;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,CAAA;AAE5C;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,SAAS,CAAA;AAE1C;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,SAAS,CAAA"}

package/dist/cjs/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\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 an 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"]}
+{"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 | undefined\n\n/**\n * Represents an 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 | undefined\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 | undefined\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> | undefined\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 | undefined\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 | undefined\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 | undefined\n"]}

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

@@ -7,17 +7,7 @@
  *
  * @group Data Groups
  */
-export type Group<Fields extends Record<string, unknown>> = Fields;
-/**
- * Represents a Legacy Group returned by the API.
- *
- * Group types are used to type Entry and Singleton objects when requesting
- * them using some SDK methods. See {@apilink DefaultModelDefinition}
- * for more info.
- *
- * @group Data Groups
- */
-export type LegacyGroup<Fields extends Record<string, unknown>> = Fields;
+export type Group<Fields extends Record<string, unknown>> = Fields | undefined;
 /**
  * Represents a Repeater Group returned by the API.
  *
@@ -32,5 +22,5 @@ export type LegacyGroup<Fields extends Record<string, unknown>> = Fields;
  *
  * @group Data Groups
  */
-export type RepeaterGroup<Fields extends Record<string, unknown>> = Fields[] | null;
+export type RepeaterGroup<Fields extends Record<string, unknown>> = Fields[] | null | undefined;
 //# sourceMappingURL=groups.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"groups.d.ts","sourceRoot":"","sources":["../../../src/types/groups.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,KAAK,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,MAAM,CAAA;AAElE;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,MAAM,CAAA;AAExE;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAC5D,MAAM,EAAE,GACR,IAAI,CAAA"}
+{"version":3,"file":"groups.d.ts","sourceRoot":"","sources":["../../../src/types/groups.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,KAAK,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,MAAM,GAAG,SAAS,CAAA;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAC5D,MAAM,EAAE,GACR,IAAI,GACJ,SAAS,CAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"groups.js","sourceRoot":"","sources":["../../../src/types/groups.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Represents a Group returned by the API.\n *\n * Group 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 Groups\n */\nexport type Group<Fields extends Record<string, unknown>> = Fields\n\n/**\n * Represents a Legacy Group returned by the API.\n *\n * Group 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 Groups\n */\nexport type LegacyGroup<Fields extends Record<string, unknown>> = Fields\n\n/**\n * Represents a Repeater Group returned by the API.\n *\n * Note that the API return empty repeaters as `null`.\n *\n * To retrieve the type of a `RepeaterGroup` item, use the\n * {@apilink RepeaterItem} utility type.\n *\n * Group 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 Groups\n */\nexport type RepeaterGroup<Fields extends Record<string, unknown>> =\n  | Fields[]\n  | null\n"]}
+{"version":3,"file":"groups.js","sourceRoot":"","sources":["../../../src/types/groups.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Represents a Group returned by the API.\n *\n * Group 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 Groups\n */\nexport type Group<Fields extends Record<string, unknown>> = Fields | undefined\n\n/**\n * Represents a Repeater Group returned by the API.\n *\n * Note that the API return empty repeaters as `null`.\n *\n * To retrieve the type of a `RepeaterGroup` item, use the\n * {@apilink RepeaterItem} utility type.\n *\n * Group 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 Groups\n */\nexport type RepeaterGroup<Fields extends Record<string, unknown>> =\n  | Fields[]\n  | null\n  | undefined\n"]}

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

@@ -6,7 +6,7 @@ import { RepeaterGroup } from './groups';
  * the `Foo` type. This is useful to "pick" the type of the content held
  * by items of a Repeater Group.
  *
- * @group Utilities
+ * @group Utility Types
  */
 export type RepeaterItem<Repeater extends RepeaterGroup<Record<string, unknown>>> = Repeater extends readonly (infer ItemType)[] ? ItemType : never;
 //# sourceMappingURL=utilities.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"utilities.js","sourceRoot":"","sources":["../../../src/types/utilities.ts"],"names":[],"mappings":"","sourcesContent":["import { RepeaterGroup } from './groups'\n\n/**\n * Returns the item type of the given Repeater Group.\n *\n * For instance, given a `RepeaterGroup<Foo>`, this utility would return\n * the `Foo` type. This is useful to \"pick\" the type of the content held\n * by items of a Repeater Group.\n *\n * @group Utilities\n */\nexport type RepeaterItem<\n  Repeater extends RepeaterGroup<Record<string, unknown>>,\n> = Repeater extends readonly (infer ItemType)[] ? ItemType : never\n"]}
+{"version":3,"file":"utilities.js","sourceRoot":"","sources":["../../../src/types/utilities.ts"],"names":[],"mappings":"","sourcesContent":["import { RepeaterGroup } from './groups'\n\n/**\n * Returns the item type of the given Repeater Group.\n *\n * For instance, given a `RepeaterGroup<Foo>`, this utility would return\n * the `Foo` type. This is useful to \"pick\" the type of the content held\n * by items of a Repeater Group.\n *\n * @group Utility Types\n */\nexport type RepeaterItem<\n  Repeater extends RepeaterGroup<Record<string, unknown>>,\n> = Repeater extends readonly (infer ItemType)[] ? ItemType : never\n"]}

package/dist/cjs/utils/image.d.ts

@@ -1,4 +1,72 @@
 import { MediaFile, MediaObject } from '../types';
-export declare const getMediaFile: (media: MediaObject, variation?: string) => MediaFile;
-export declare const getMediaSource: (media: MediaObject, variation?: string) => string;
+/**
+ * Returns the given variation of the provided MediaObject.
+ *
+ * @param media The MediaObject to analyze. If undefined, the function will also
+ * return undefined.
+ * @param variation A string or array of strings with the variation name that
+ * should be returned. If an array is given, the first variation found will
+ * be returned.
+ *
+ * @returns The MediaFile of the first given variation found. If the provided
+ * variations weren't found, or if no variation parameter was provided, returns
+ * the optimized variation file (if it exists) or the original file. Returns
+ * undefined if no media object is provided.
+ *
+ * @example Getting the optimized or original file of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaFile } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `info.featured_image` is the path of an arbitrary Media content field.
+ * const file = getMediaFile(response.data.data.info.featured_image)
+ * ```
+ *
+ * @category Media Utilities
+ */
+export declare const getMediaFile: (media?: MediaObject, variation?: string | string[]) => MediaFile | undefined;
+/**
+ * Returns the source URL of the optimized file (if it exists) or the original
+ * file of the given MediaObject. If the variation parameter is provided,
+ * returns the source URL of that variation instead, if it exists, but falls
+ * back to the optimized or original files if it doesn't.
+ *
+ * @param media The MediaObject to analyze. If undefined, the function will also
+ * return undefined.
+ * @param variation A string or array of strings with the variation name that
+ * should be returned. If an array is given, the first variation found will
+ * be returned.
+ *
+ * @returns The source URL of the first given variation found. If the provided
+ * variations weren't found, or if no variation parameter was provided, returns
+ * the optimized variation source URL (if it exists) or the original source URL.
+ * Returns undefined if no media object is provided.
+ *
+ * @example Getting the optimized or original source URL of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `content.background` is the path of an arbitrary Media content field.
+ * const imageUrl = getMediaSource(response.data.data.content.background)
+ * ```
+ *
+ * @example Getting the source URL of a specific variation of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `content.background` is the path of an arbitrary Media content field.
+ * const imageUrl = getMediaSource(
+ *   response.data.data.content.background,
+ *   ['large', 'medium']
+ * )
+ * ```
+ *
+ * @category Media Utilities
+ */
+export declare function getMediaSource(media?: MediaObject, variation?: string | string[]): string | undefined;
 //# sourceMappingURL=image.d.ts.map

package/dist/cjs/utils/image.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../../src/utils/image.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AASjD,eAAO,MAAM,YAAY,GACvB,OAAO,WAAW,EAClB,YAAY,MAAM,KACjB,SASF,CAAA;AAED,eAAO,MAAM,cAAc,GACzB,OAAO,WAAW,EAClB,YAAY,MAAM,KACjB,MAEF,CAAA"}
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../../src/utils/image.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAejD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,YAAY,GACvB,QAAQ,WAAW,EACnB,YAAY,MAAM,GAAG,MAAM,EAAE,KAC5B,SAAS,GAAG,SAgBd,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,cAAc,CAC5B,KAAK,CAAC,EAAE,WAAW,EACnB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,sBAG9B"}

package/dist/cjs/utils/image.js

@@ -1,20 +1,101 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getMediaSource = exports.getMediaFile = void 0;
+exports.getMediaFile = void 0;
+exports.getMediaSource = getMediaSource;
+/**
+ * Returns the optimized variation file of the given MediaObject
+ * or the original file if the optimized variation doesn't exist.
+ *
+ * @param media The MediaObject to analyze.
+ */
 const getOptimizedOrOriginal = (media) => {
     var _a;
     return ((_a = media.files.find((file) => file.variation === 'optimized')) !== null && _a !== void 0 ? _a : media.files.find((file) => file.variation === 'original'));
 };
+/**
+ * Returns the given variation of the provided MediaObject.
+ *
+ * @param media The MediaObject to analyze. If undefined, the function will also
+ * return undefined.
+ * @param variation A string or array of strings with the variation name that
+ * should be returned. If an array is given, the first variation found will
+ * be returned.
+ *
+ * @returns The MediaFile of the first given variation found. If the provided
+ * variations weren't found, or if no variation parameter was provided, returns
+ * the optimized variation file (if it exists) or the original file. Returns
+ * undefined if no media object is provided.
+ *
+ * @example Getting the optimized or original file of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaFile } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `info.featured_image` is the path of an arbitrary Media content field.
+ * const file = getMediaFile(response.data.data.info.featured_image)
+ * ```
+ *
+ * @category Media Utilities
+ */
 const getMediaFile = (media, variation) => {
-    var _a;
+    if (!media)
+        return undefined;
     if (variation) {
-        return ((_a = media.files.find((file) => file.variation === variation)) !== null && _a !== void 0 ? _a : getOptimizedOrOriginal(media));
+        const variationArray = Array.isArray(variation) ? variation : [variation];
+        for (const variationName of variationArray) {
+            const file = media.files.find((file) => file.variation === variationName);
+            if (file) {
+                return file;
+            }
+        }
     }
     return getOptimizedOrOriginal(media);
 };
 exports.getMediaFile = getMediaFile;
-const getMediaSource = (media, variation) => {
-    return (0, exports.getMediaFile)(media, variation).path;
-};
-exports.getMediaSource = getMediaSource;
+/**
+ * Returns the source URL of the optimized file (if it exists) or the original
+ * file of the given MediaObject. If the variation parameter is provided,
+ * returns the source URL of that variation instead, if it exists, but falls
+ * back to the optimized or original files if it doesn't.
+ *
+ * @param media The MediaObject to analyze. If undefined, the function will also
+ * return undefined.
+ * @param variation A string or array of strings with the variation name that
+ * should be returned. If an array is given, the first variation found will
+ * be returned.
+ *
+ * @returns The source URL of the first given variation found. If the provided
+ * variations weren't found, or if no variation parameter was provided, returns
+ * the optimized variation source URL (if it exists) or the original source URL.
+ * Returns undefined if no media object is provided.
+ *
+ * @example Getting the optimized or original source URL of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `content.background` is the path of an arbitrary Media content field.
+ * const imageUrl = getMediaSource(response.data.data.content.background)
+ * ```
+ *
+ * @example Getting the source URL of a specific variation of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `content.background` is the path of an arbitrary Media content field.
+ * const imageUrl = getMediaSource(
+ *   response.data.data.content.background,
+ *   ['large', 'medium']
+ * )
+ * ```
+ *
+ * @category Media Utilities
+ */
+function getMediaSource(media, variation) {
+    return media ? (0, exports.getMediaFile)(media, variation).path : undefined;
+}
 //# sourceMappingURL=image.js.map

package/dist/cjs/utils/image.js.map

@@ -1 +1 @@
-{"version":3,"file":"image.js","sourceRoot":"","sources":["../../../src/utils/image.ts"],"names":[],"mappings":";;;AAEA,MAAM,sBAAsB,GAAG,CAAC,KAAkB,EAAE,EAAE;;IACpD,OAAO,CACL,MAAA,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,WAAW,CAAC,mCACzD,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,UAAU,CAAe,CACzE,CAAA;AACH,CAAC,CAAA;AAEM,MAAM,YAAY,GAAG,CAC1B,KAAkB,EAClB,SAAkB,EACP,EAAE;;IACb,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,CACL,MAAA,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,mCACxD,sBAAsB,CAAC,KAAK,CAAC,CAC9B,CAAA;IACH,CAAC;IAED,OAAO,sBAAsB,CAAC,KAAK,CAAC,CAAA;AACtC,CAAC,CAAA;AAZY,QAAA,YAAY,gBAYxB;AAEM,MAAM,cAAc,GAAG,CAC5B,KAAkB,EAClB,SAAkB,EACV,EAAE;IACV,OAAO,IAAA,oBAAY,EAAC,KAAK,EAAE,SAAS,CAAC,CAAC,IAAI,CAAA;AAC5C,CAAC,CAAA;AALY,QAAA,cAAc,kBAK1B","sourcesContent":["import { MediaFile, MediaObject } from '../types'\n\nconst getOptimizedOrOriginal = (media: MediaObject) => {\n  return (\n    media.files.find((file) => file.variation === 'optimized') ??\n    (media.files.find((file) => file.variation === 'original') as MediaFile)\n  )\n}\n\nexport const getMediaFile = (\n  media: MediaObject,\n  variation?: string\n): MediaFile => {\n  if (variation) {\n    return (\n      media.files.find((file) => file.variation === variation) ??\n      getOptimizedOrOriginal(media)\n    )\n  }\n\n  return getOptimizedOrOriginal(media)\n}\n\nexport const getMediaSource = (\n  media: MediaObject,\n  variation?: string\n): string => {\n  return getMediaFile(media, variation).path\n}\n"]}
+{"version":3,"file":"image.js","sourceRoot":"","sources":["../../../src/utils/image.ts"],"names":[],"mappings":";;;AAwGA,wCAKC;AA3GD;;;;;GAKG;AACH,MAAM,sBAAsB,GAAG,CAAC,KAAkB,EAAE,EAAE;;IACpD,OAAO,CACL,MAAA,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,WAAW,CAAC,mCACzD,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,UAAU,CAAe,CACzE,CAAA;AACH,CAAC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACI,MAAM,YAAY,GAAG,CAC1B,KAAmB,EACnB,SAA6B,EACN,EAAE;IACzB,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAA;IAE5B,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;QAEzE,KAAK,MAAM,aAAa,IAAI,cAAc,EAAE,CAAC;YAC3C,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,aAAa,CAAC,CAAA;YAEzE,IAAI,IAAI,EAAE,CAAC;gBACT,OAAO,IAAI,CAAA;YACb,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,sBAAsB,CAAC,KAAK,CAAC,CAAA;AACtC,CAAC,CAAA;AAnBY,QAAA,YAAY,gBAmBxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,SAAgB,cAAc,CAC5B,KAAmB,EACnB,SAA6B;IAE7B,OAAO,KAAK,CAAC,CAAC,CAAC,IAAA,oBAAY,EAAC,KAAK,EAAE,SAAS,CAAE,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;AACjE,CAAC","sourcesContent":["import { MediaFile, MediaObject } from '../types'\n\n/**\n * Returns the optimized variation file of the given MediaObject\n * or the original file if the optimized variation doesn't exist.\n *\n * @param media The MediaObject to analyze.\n */\nconst getOptimizedOrOriginal = (media: MediaObject) => {\n  return (\n    media.files.find((file) => file.variation === 'optimized') ??\n    (media.files.find((file) => file.variation === 'original') as MediaFile)\n  )\n}\n\n/**\n * Returns the given variation of the provided MediaObject.\n *\n * @param media The MediaObject to analyze. If undefined, the function will also\n * return undefined.\n * @param variation A string or array of strings with the variation name that\n * should be returned. If an array is given, the first variation found will\n * be returned.\n *\n * @returns The MediaFile of the first given variation found. If the provided\n * variations weren't found, or if no variation parameter was provided, returns\n * the optimized variation file (if it exists) or the original file. Returns\n * undefined if no media object is provided.\n *\n * @example Getting the optimized or original file of the given MediaObject.\n * ```ts\n * import Starlight, { getMediaFile } from '@starlightcms/js-sdk'\n *\n * const response = await Starlight.posts.entries.get('foo')\n *\n * // `info.featured_image` is the path of an arbitrary Media content field.\n * const file = getMediaFile(response.data.data.info.featured_image)\n * ```\n *\n * @category Media Utilities\n */\nexport const getMediaFile = (\n  media?: MediaObject,\n  variation?: string | string[],\n): MediaFile | undefined => {\n  if (!media) return undefined\n\n  if (variation) {\n    const variationArray = Array.isArray(variation) ? variation : [variation]\n\n    for (const variationName of variationArray) {\n      const file = media.files.find((file) => file.variation === variationName)\n\n      if (file) {\n        return file\n      }\n    }\n  }\n\n  return getOptimizedOrOriginal(media)\n}\n\n/**\n * Returns the source URL of the optimized file (if it exists) or the original\n * file of the given MediaObject. If the variation parameter is provided,\n * returns the source URL of that variation instead, if it exists, but falls\n * back to the optimized or original files if it doesn't.\n *\n * @param media The MediaObject to analyze. If undefined, the function will also\n * return undefined.\n * @param variation A string or array of strings with the variation name that\n * should be returned. If an array is given, the first variation found will\n * be returned.\n *\n * @returns The source URL of the first given variation found. If the provided\n * variations weren't found, or if no variation parameter was provided, returns\n * the optimized variation source URL (if it exists) or the original source URL.\n * Returns undefined if no media object is provided.\n *\n * @example Getting the optimized or original source URL of the given MediaObject.\n * ```ts\n * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'\n *\n * const response = await Starlight.posts.entries.get('foo')\n *\n * // `content.background` is the path of an arbitrary Media content field.\n * const imageUrl = getMediaSource(response.data.data.content.background)\n * ```\n *\n * @example Getting the source URL of a specific variation of the given MediaObject.\n * ```ts\n * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'\n *\n * const response = await Starlight.posts.entries.get('foo')\n *\n * // `content.background` is the path of an arbitrary Media content field.\n * const imageUrl = getMediaSource(\n *   response.data.data.content.background,\n *   ['large', 'medium']\n * )\n * ```\n *\n * @category Media Utilities\n */\nexport function getMediaSource(\n  media?: MediaObject,\n  variation?: string | string[],\n) {\n  return media ? getMediaFile(media, variation)!.path : undefined\n}\n"]}

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

@@ -9,7 +9,7 @@ import { VisualData } from './visual';
  *
  * @group Data Fields
  */
-export type BooleanField = boolean;
+export type BooleanField = boolean | undefined;
 /**
  * Represents an HTML Field returned by the API.
  *
@@ -19,7 +19,7 @@ export type BooleanField = boolean;
  *
  * @group Data Fields
  */
-export type HtmlField = string;
+export type HtmlField = string | undefined;
 /**
  * Represents a Media Field returned by the API.
  *
@@ -29,7 +29,7 @@ export type HtmlField = string;
  *
  * @group Data Fields
  */
-export type MediaField = MediaObject;
+export type MediaField = MediaObject | undefined;
 /**
  * Represents a Relation Field returned by the API.
  *
@@ -39,7 +39,7 @@ export type MediaField = MediaObject;
  *
  * @group Data Fields
  */
-export type RelationField<T> = Relation<T>;
+export type RelationField<T> = Relation<T> | undefined;
 /**
  * Represents a String Field returned by the API.
  *
@@ -49,7 +49,7 @@ export type RelationField<T> = Relation<T>;
  *
  * @group Data Fields
  */
-export type StringField = string;
+export type StringField = string | undefined;
 /**
  * Represents a Text Field returned by the API.
  *
@@ -59,7 +59,7 @@ export type StringField = string;
  *
  * @group Data Fields
  */
-export type TextField = string;
+export type TextField = string | undefined;
 /**
  * Represents a Visual Field returned by the API.
  *
@@ -69,5 +69,5 @@ export type TextField = string;
  *
  * @group Data Fields
  */
-export type VisualField = VisualData;
+export type VisualField = VisualData | undefined;
 //# 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;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,CAAA;AAElC;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAA;AAE9B;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,CAAA;AAEpC;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAA;AAE1C;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAA;AAEhC;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAA;AAE9B;;;;;;;;GAQG;AACH,MAAM,MAAM,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,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,SAAS,CAAA;AAE9C;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,SAAS,CAAA;AAE1C;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,SAAS,CAAA;AAEhD;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,GAAG,SAAS,CAAA;AAEtD;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,CAAA;AAE5C;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,SAAS,CAAA;AAE1C;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,SAAS,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\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 an 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"]}
+{"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 | undefined\n\n/**\n * Represents an 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 | undefined\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 | undefined\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> | undefined\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 | undefined\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 | undefined\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 | undefined\n"]}

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

@@ -7,17 +7,7 @@
  *
  * @group Data Groups
  */
-export type Group<Fields extends Record<string, unknown>> = Fields;
-/**
- * Represents a Legacy Group returned by the API.
- *
- * Group types are used to type Entry and Singleton objects when requesting
- * them using some SDK methods. See {@apilink DefaultModelDefinition}
- * for more info.
- *
- * @group Data Groups
- */
-export type LegacyGroup<Fields extends Record<string, unknown>> = Fields;
+export type Group<Fields extends Record<string, unknown>> = Fields | undefined;
 /**
  * Represents a Repeater Group returned by the API.
  *
@@ -32,5 +22,5 @@ export type LegacyGroup<Fields extends Record<string, unknown>> = Fields;
  *
  * @group Data Groups
  */
-export type RepeaterGroup<Fields extends Record<string, unknown>> = Fields[] | null;
+export type RepeaterGroup<Fields extends Record<string, unknown>> = Fields[] | null | undefined;
 //# sourceMappingURL=groups.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"groups.d.ts","sourceRoot":"","sources":["../../../src/types/groups.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,KAAK,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,MAAM,CAAA;AAElE;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,MAAM,CAAA;AAExE;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAC5D,MAAM,EAAE,GACR,IAAI,CAAA"}
+{"version":3,"file":"groups.d.ts","sourceRoot":"","sources":["../../../src/types/groups.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,KAAK,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,MAAM,GAAG,SAAS,CAAA;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAC5D,MAAM,EAAE,GACR,IAAI,GACJ,SAAS,CAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"groups.js","sourceRoot":"","sources":["../../../src/types/groups.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Represents a Group returned by the API.\n *\n * Group 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 Groups\n */\nexport type Group<Fields extends Record<string, unknown>> = Fields\n\n/**\n * Represents a Legacy Group returned by the API.\n *\n * Group 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 Groups\n */\nexport type LegacyGroup<Fields extends Record<string, unknown>> = Fields\n\n/**\n * Represents a Repeater Group returned by the API.\n *\n * Note that the API return empty repeaters as `null`.\n *\n * To retrieve the type of a `RepeaterGroup` item, use the\n * {@apilink RepeaterItem} utility type.\n *\n * Group 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 Groups\n */\nexport type RepeaterGroup<Fields extends Record<string, unknown>> =\n  | Fields[]\n  | null\n"]}
+{"version":3,"file":"groups.js","sourceRoot":"","sources":["../../../src/types/groups.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Represents a Group returned by the API.\n *\n * Group 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 Groups\n */\nexport type Group<Fields extends Record<string, unknown>> = Fields | undefined\n\n/**\n * Represents a Repeater Group returned by the API.\n *\n * Note that the API return empty repeaters as `null`.\n *\n * To retrieve the type of a `RepeaterGroup` item, use the\n * {@apilink RepeaterItem} utility type.\n *\n * Group 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 Groups\n */\nexport type RepeaterGroup<Fields extends Record<string, unknown>> =\n  | Fields[]\n  | null\n  | undefined\n"]}

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

@@ -6,7 +6,7 @@ import { RepeaterGroup } from './groups';
  * the `Foo` type. This is useful to "pick" the type of the content held
  * by items of a Repeater Group.
  *
- * @group Utilities
+ * @group Utility Types
  */
 export type RepeaterItem<Repeater extends RepeaterGroup<Record<string, unknown>>> = Repeater extends readonly (infer ItemType)[] ? ItemType : never;
 //# sourceMappingURL=utilities.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"utilities.js","sourceRoot":"","sources":["../../../src/types/utilities.ts"],"names":[],"mappings":"","sourcesContent":["import { RepeaterGroup } from './groups'\n\n/**\n * Returns the item type of the given Repeater Group.\n *\n * For instance, given a `RepeaterGroup<Foo>`, this utility would return\n * the `Foo` type. This is useful to \"pick\" the type of the content held\n * by items of a Repeater Group.\n *\n * @group Utilities\n */\nexport type RepeaterItem<\n  Repeater extends RepeaterGroup<Record<string, unknown>>,\n> = Repeater extends readonly (infer ItemType)[] ? ItemType : never\n"]}
+{"version":3,"file":"utilities.js","sourceRoot":"","sources":["../../../src/types/utilities.ts"],"names":[],"mappings":"","sourcesContent":["import { RepeaterGroup } from './groups'\n\n/**\n * Returns the item type of the given Repeater Group.\n *\n * For instance, given a `RepeaterGroup<Foo>`, this utility would return\n * the `Foo` type. This is useful to \"pick\" the type of the content held\n * by items of a Repeater Group.\n *\n * @group Utility Types\n */\nexport type RepeaterItem<\n  Repeater extends RepeaterGroup<Record<string, unknown>>,\n> = Repeater extends readonly (infer ItemType)[] ? ItemType : never\n"]}

package/dist/esm/utils/image.d.ts

@@ -1,4 +1,72 @@
 import { MediaFile, MediaObject } from '../types';
-export declare const getMediaFile: (media: MediaObject, variation?: string) => MediaFile;
-export declare const getMediaSource: (media: MediaObject, variation?: string) => string;
+/**
+ * Returns the given variation of the provided MediaObject.
+ *
+ * @param media The MediaObject to analyze. If undefined, the function will also
+ * return undefined.
+ * @param variation A string or array of strings with the variation name that
+ * should be returned. If an array is given, the first variation found will
+ * be returned.
+ *
+ * @returns The MediaFile of the first given variation found. If the provided
+ * variations weren't found, or if no variation parameter was provided, returns
+ * the optimized variation file (if it exists) or the original file. Returns
+ * undefined if no media object is provided.
+ *
+ * @example Getting the optimized or original file of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaFile } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `info.featured_image` is the path of an arbitrary Media content field.
+ * const file = getMediaFile(response.data.data.info.featured_image)
+ * ```
+ *
+ * @category Media Utilities
+ */
+export declare const getMediaFile: (media?: MediaObject, variation?: string | string[]) => MediaFile | undefined;
+/**
+ * Returns the source URL of the optimized file (if it exists) or the original
+ * file of the given MediaObject. If the variation parameter is provided,
+ * returns the source URL of that variation instead, if it exists, but falls
+ * back to the optimized or original files if it doesn't.
+ *
+ * @param media The MediaObject to analyze. If undefined, the function will also
+ * return undefined.
+ * @param variation A string or array of strings with the variation name that
+ * should be returned. If an array is given, the first variation found will
+ * be returned.
+ *
+ * @returns The source URL of the first given variation found. If the provided
+ * variations weren't found, or if no variation parameter was provided, returns
+ * the optimized variation source URL (if it exists) or the original source URL.
+ * Returns undefined if no media object is provided.
+ *
+ * @example Getting the optimized or original source URL of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `content.background` is the path of an arbitrary Media content field.
+ * const imageUrl = getMediaSource(response.data.data.content.background)
+ * ```
+ *
+ * @example Getting the source URL of a specific variation of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `content.background` is the path of an arbitrary Media content field.
+ * const imageUrl = getMediaSource(
+ *   response.data.data.content.background,
+ *   ['large', 'medium']
+ * )
+ * ```
+ *
+ * @category Media Utilities
+ */
+export declare function getMediaSource(media?: MediaObject, variation?: string | string[]): string | undefined;
 //# sourceMappingURL=image.d.ts.map

package/dist/esm/utils/image.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../../src/utils/image.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AASjD,eAAO,MAAM,YAAY,GACvB,OAAO,WAAW,EAClB,YAAY,MAAM,KACjB,SASF,CAAA;AAED,eAAO,MAAM,cAAc,GACzB,OAAO,WAAW,EAClB,YAAY,MAAM,KACjB,MAEF,CAAA"}
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../../src/utils/image.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAejD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,YAAY,GACvB,QAAQ,WAAW,EACnB,YAAY,MAAM,GAAG,MAAM,EAAE,KAC5B,SAAS,GAAG,SAgBd,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,cAAc,CAC5B,KAAK,CAAC,EAAE,WAAW,EACnB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,sBAG9B"}

package/dist/esm/utils/image.js

@@ -1,15 +1,96 @@
+/**
+ * Returns the optimized variation file of the given MediaObject
+ * or the original file if the optimized variation doesn't exist.
+ *
+ * @param media The MediaObject to analyze.
+ */
 const getOptimizedOrOriginal = (media) => {
     var _a;
     return ((_a = media.files.find((file) => file.variation === 'optimized')) !== null && _a !== void 0 ? _a : media.files.find((file) => file.variation === 'original'));
 };
+/**
+ * Returns the given variation of the provided MediaObject.
+ *
+ * @param media The MediaObject to analyze. If undefined, the function will also
+ * return undefined.
+ * @param variation A string or array of strings with the variation name that
+ * should be returned. If an array is given, the first variation found will
+ * be returned.
+ *
+ * @returns The MediaFile of the first given variation found. If the provided
+ * variations weren't found, or if no variation parameter was provided, returns
+ * the optimized variation file (if it exists) or the original file. Returns
+ * undefined if no media object is provided.
+ *
+ * @example Getting the optimized or original file of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaFile } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `info.featured_image` is the path of an arbitrary Media content field.
+ * const file = getMediaFile(response.data.data.info.featured_image)
+ * ```
+ *
+ * @category Media Utilities
+ */
 export const getMediaFile = (media, variation) => {
-    var _a;
+    if (!media)
+        return undefined;
     if (variation) {
-        return ((_a = media.files.find((file) => file.variation === variation)) !== null && _a !== void 0 ? _a : getOptimizedOrOriginal(media));
+        const variationArray = Array.isArray(variation) ? variation : [variation];
+        for (const variationName of variationArray) {
+            const file = media.files.find((file) => file.variation === variationName);
+            if (file) {
+                return file;
+            }
+        }
     }
     return getOptimizedOrOriginal(media);
 };
-export const getMediaSource = (media, variation) => {
-    return getMediaFile(media, variation).path;
-};
+/**
+ * Returns the source URL of the optimized file (if it exists) or the original
+ * file of the given MediaObject. If the variation parameter is provided,
+ * returns the source URL of that variation instead, if it exists, but falls
+ * back to the optimized or original files if it doesn't.
+ *
+ * @param media The MediaObject to analyze. If undefined, the function will also
+ * return undefined.
+ * @param variation A string or array of strings with the variation name that
+ * should be returned. If an array is given, the first variation found will
+ * be returned.
+ *
+ * @returns The source URL of the first given variation found. If the provided
+ * variations weren't found, or if no variation parameter was provided, returns
+ * the optimized variation source URL (if it exists) or the original source URL.
+ * Returns undefined if no media object is provided.
+ *
+ * @example Getting the optimized or original source URL of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `content.background` is the path of an arbitrary Media content field.
+ * const imageUrl = getMediaSource(response.data.data.content.background)
+ * ```
+ *
+ * @example Getting the source URL of a specific variation of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `content.background` is the path of an arbitrary Media content field.
+ * const imageUrl = getMediaSource(
+ *   response.data.data.content.background,
+ *   ['large', 'medium']
+ * )
+ * ```
+ *
+ * @category Media Utilities
+ */
+export function getMediaSource(media, variation) {
+    return media ? getMediaFile(media, variation).path : undefined;
+}
 //# sourceMappingURL=image.js.map

package/dist/esm/utils/image.js.map

@@ -1 +1 @@
-{"version":3,"file":"image.js","sourceRoot":"","sources":["../../../src/utils/image.ts"],"names":[],"mappings":"AAEA,MAAM,sBAAsB,GAAG,CAAC,KAAkB,EAAE,EAAE;;IACpD,OAAO,CACL,MAAA,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,WAAW,CAAC,mCACzD,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,UAAU,CAAe,CACzE,CAAA;AACH,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,KAAkB,EAClB,SAAkB,EACP,EAAE;;IACb,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,CACL,MAAA,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,mCACxD,sBAAsB,CAAC,KAAK,CAAC,CAC9B,CAAA;IACH,CAAC;IAED,OAAO,sBAAsB,CAAC,KAAK,CAAC,CAAA;AACtC,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,KAAkB,EAClB,SAAkB,EACV,EAAE;IACV,OAAO,YAAY,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,IAAI,CAAA;AAC5C,CAAC,CAAA","sourcesContent":["import { MediaFile, MediaObject } from '../types'\n\nconst getOptimizedOrOriginal = (media: MediaObject) => {\n  return (\n    media.files.find((file) => file.variation === 'optimized') ??\n    (media.files.find((file) => file.variation === 'original') as MediaFile)\n  )\n}\n\nexport const getMediaFile = (\n  media: MediaObject,\n  variation?: string\n): MediaFile => {\n  if (variation) {\n    return (\n      media.files.find((file) => file.variation === variation) ??\n      getOptimizedOrOriginal(media)\n    )\n  }\n\n  return getOptimizedOrOriginal(media)\n}\n\nexport const getMediaSource = (\n  media: MediaObject,\n  variation?: string\n): string => {\n  return getMediaFile(media, variation).path\n}\n"]}
+{"version":3,"file":"image.js","sourceRoot":"","sources":["../../../src/utils/image.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,sBAAsB,GAAG,CAAC,KAAkB,EAAE,EAAE;;IACpD,OAAO,CACL,MAAA,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,WAAW,CAAC,mCACzD,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,UAAU,CAAe,CACzE,CAAA;AACH,CAAC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,KAAmB,EACnB,SAA6B,EACN,EAAE;IACzB,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAA;IAE5B,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;QAEzE,KAAK,MAAM,aAAa,IAAI,cAAc,EAAE,CAAC;YAC3C,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,aAAa,CAAC,CAAA;YAEzE,IAAI,IAAI,EAAE,CAAC;gBACT,OAAO,IAAI,CAAA;YACb,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,sBAAsB,CAAC,KAAK,CAAC,CAAA;AACtC,CAAC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAmB,EACnB,SAA6B;IAE7B,OAAO,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,EAAE,SAAS,CAAE,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;AACjE,CAAC","sourcesContent":["import { MediaFile, MediaObject } from '../types'\n\n/**\n * Returns the optimized variation file of the given MediaObject\n * or the original file if the optimized variation doesn't exist.\n *\n * @param media The MediaObject to analyze.\n */\nconst getOptimizedOrOriginal = (media: MediaObject) => {\n  return (\n    media.files.find((file) => file.variation === 'optimized') ??\n    (media.files.find((file) => file.variation === 'original') as MediaFile)\n  )\n}\n\n/**\n * Returns the given variation of the provided MediaObject.\n *\n * @param media The MediaObject to analyze. If undefined, the function will also\n * return undefined.\n * @param variation A string or array of strings with the variation name that\n * should be returned. If an array is given, the first variation found will\n * be returned.\n *\n * @returns The MediaFile of the first given variation found. If the provided\n * variations weren't found, or if no variation parameter was provided, returns\n * the optimized variation file (if it exists) or the original file. Returns\n * undefined if no media object is provided.\n *\n * @example Getting the optimized or original file of the given MediaObject.\n * ```ts\n * import Starlight, { getMediaFile } from '@starlightcms/js-sdk'\n *\n * const response = await Starlight.posts.entries.get('foo')\n *\n * // `info.featured_image` is the path of an arbitrary Media content field.\n * const file = getMediaFile(response.data.data.info.featured_image)\n * ```\n *\n * @category Media Utilities\n */\nexport const getMediaFile = (\n  media?: MediaObject,\n  variation?: string | string[],\n): MediaFile | undefined => {\n  if (!media) return undefined\n\n  if (variation) {\n    const variationArray = Array.isArray(variation) ? variation : [variation]\n\n    for (const variationName of variationArray) {\n      const file = media.files.find((file) => file.variation === variationName)\n\n      if (file) {\n        return file\n      }\n    }\n  }\n\n  return getOptimizedOrOriginal(media)\n}\n\n/**\n * Returns the source URL of the optimized file (if it exists) or the original\n * file of the given MediaObject. If the variation parameter is provided,\n * returns the source URL of that variation instead, if it exists, but falls\n * back to the optimized or original files if it doesn't.\n *\n * @param media The MediaObject to analyze. If undefined, the function will also\n * return undefined.\n * @param variation A string or array of strings with the variation name that\n * should be returned. If an array is given, the first variation found will\n * be returned.\n *\n * @returns The source URL of the first given variation found. If the provided\n * variations weren't found, or if no variation parameter was provided, returns\n * the optimized variation source URL (if it exists) or the original source URL.\n * Returns undefined if no media object is provided.\n *\n * @example Getting the optimized or original source URL of the given MediaObject.\n * ```ts\n * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'\n *\n * const response = await Starlight.posts.entries.get('foo')\n *\n * // `content.background` is the path of an arbitrary Media content field.\n * const imageUrl = getMediaSource(response.data.data.content.background)\n * ```\n *\n * @example Getting the source URL of a specific variation of the given MediaObject.\n * ```ts\n * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'\n *\n * const response = await Starlight.posts.entries.get('foo')\n *\n * // `content.background` is the path of an arbitrary Media content field.\n * const imageUrl = getMediaSource(\n *   response.data.data.content.background,\n *   ['large', 'medium']\n * )\n * ```\n *\n * @category Media Utilities\n */\nexport function getMediaSource(\n  media?: MediaObject,\n  variation?: string | string[],\n) {\n  return media ? getMediaFile(media, variation)!.path : undefined\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlightcms/js-sdk",
-  "version": "3.2.0",
+  "version": "4.0.0-beta.1",
   "description": "The Starlight SDK for JavaScript",
   "main": "dist/cjs/index.js",
   "exports": {