@starlightcms/js-sdk 4.0.0-beta.2 → 4.0.0-beta.3

package/dist/index.cjs

@@ -0,0 +1,397 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+//#region src/errors.ts
+/**
+* This error is thrown every time a problem occurs when requesting something
+* from Starlight's APIs. When it does, you can inspect the attached response
+* to verify what kind of problem happened and handle it accordingly.
+*
+* @group Errors
+*/
+var StarlightError = class extends Error {
+	constructor(message, response) {
+		super(message);
+		this.response = response;
+	}
+};
+//#endregion
+//#region src/selectors/Entry/index.ts
+function makeEntrySelector(client, model) {
+	return {
+		list(params, options) {
+			return client.get(`/models/${model}/entries`, params, options);
+		},
+		get(slug, params, options) {
+			return client.get(`/models/${model}/entries/${slug}`, params, options);
+		}
+	};
+}
+//#endregion
+//#region src/instances/ModelCategory/index.ts
+function makeModelCategoryInstance(client, model, category) {
+	return {
+		get(params, options) {
+			return client.get(`/models/${model}/categories/${category}`, params, options);
+		},
+		entries(params, options) {
+			return client.get(`/models/${model}/categories/${category}/entries`, params, options);
+		}
+	};
+}
+//#endregion
+//#region src/selectors/ModelCategory/index.ts
+function makeModelCategorySelector(client, model) {
+	return new Proxy({
+		list(params, options) {
+			return client.get(`/models/${model}/categories`, params, options);
+		},
+		get(slug, params, options) {
+			return client.get(`/models/${model}/categories/${slug}`, params, options);
+		}
+	}, { get(target, prop) {
+		if (typeof prop === "string" && !Reflect.has(target, prop)) return makeModelCategoryInstance(client, model, prop);
+		return Reflect.get(target, prop);
+	} });
+}
+//#endregion
+//#region src/instances/Model/index.ts
+function makeModelInstance(client, model) {
+	return new Proxy({
+		get(params, options) {
+			return client.get(`/models/${model}`, params, options);
+		},
+		category(slug) {
+			return makeModelCategoryInstance(client, model, slug);
+		},
+		get entries() {
+			return makeEntrySelector(client, model);
+		},
+		get categories() {
+			return makeModelCategorySelector(client, model);
+		}
+	}, { get(target, prop) {
+		if (typeof prop === "string" && !Reflect.has(target, prop)) return makeModelCategoryInstance(client, model, prop);
+		return Reflect.get(target, prop);
+	} });
+}
+//#endregion
+//#region src/selectors/Model/index.ts
+function makeModelSelector(client) {
+	return new Proxy({
+		list(params, options) {
+			return client.get("/models", params, options);
+		},
+		get(slug, params, options) {
+			return client.get(`/models/${slug}`, params, options);
+		}
+	}, { get(target, prop) {
+		if (typeof prop === "string" && !Reflect.has(target, prop)) return makeModelInstance(client, prop);
+		return Reflect.get(target, prop);
+	} });
+}
+//#endregion
+//#region src/selectors/Singleton/index.ts
+function makeSingletonSelector(client) {
+	return {
+		list(params, options) {
+			return client.get("/singletons", params, options);
+		},
+		get(slug, params, options) {
+			return client.get(`/singletons/${slug}`, params, options);
+		}
+	};
+}
+//#endregion
+//#region src/instances/Collection/index.ts
+function makeCollectionInstance(client, collection) {
+	return {
+		get(params, options) {
+			return client.get(`/collections/${collection}`, params, options);
+		},
+		items(params, options) {
+			return client.get(`/collections/${collection}/items`, params, options);
+		}
+	};
+}
+//#endregion
+//#region src/selectors/Collection/index.ts
+function makeCollectionSelector(client) {
+	return new Proxy({
+		list(params, options) {
+			return client.get("/collections", params, options);
+		},
+		get(slug, params, options) {
+			return client.get(`/collections/${slug}`, params, options);
+		}
+	}, { get(target, prop) {
+		if (typeof prop === "string" && !Reflect.has(target, prop)) return makeCollectionInstance(client, prop);
+		return Reflect.get(target, prop);
+	} });
+}
+//#endregion
+//#region src/selectors/Media/index.ts
+function makeMediaSelector(client) {
+	return {
+		list(params, options) {
+			return client.get("/media", params, options);
+		},
+		get(id, params, options) {
+			return client.get(`/media/${id}`, params, options);
+		}
+	};
+}
+//#endregion
+//#region src/selectors/Search/index.ts
+function makeSearchSelector(client) {
+	return { entries(params, options) {
+		return client.get("/search/entries", params, options);
+	} };
+}
+//#endregion
+//#region src/instances/Form/index.ts
+function makeFormInstance(client, form) {
+	return {
+		get(params, options) {
+			return client.get(`/forms/${form}`, params, options);
+		},
+		schema(params, options) {
+			return client.get(`/forms/${form}/schema`, params, options);
+		}
+	};
+}
+//#endregion
+//#region src/selectors/Form/index.ts
+function makeFormSelector(client) {
+	return new Proxy({}, { get(target, prop) {
+		if (typeof prop === "string" && !Reflect.has(target, prop)) return makeFormInstance(client, prop);
+		return Reflect.get(target, prop);
+	} });
+}
+//#endregion
+//#region src/client.ts
+/**
+* Returns a new {@link DynamicStarlightClient}, which is a
+* {@link StarlightClient} with support to create
+* {@apilink ModelInstance | ModelInstances} using the dynamic syntax. To learn
+* which methods a client supports, see {@link StarlightClient}.
+*
+* This function accepts a {@link StarlightConfig} object and can be used to
+* create new clients that connect to a single Starlight workspace. Each client
+* returned by this function is separate and independent of the others.
+*
+* If you only need to make requests to a single workspace, it's probably easier
+* to use the SDK's default client. To use it, you only need to
+* import the default object exported by the SDK:
+*
+*  ```ts
+* // `Starlight` below is the default StarlightClient.
+* import Starlight from '@starlightcms/js-sdk'
+* ```
+*
+* See {@link default} for more info on how to use the default client.
+*
+* @example Creating a new client and exporting it.
+*  ```ts
+* import { makeStarlightClient } from '@starlightcms/js-sdk'
+*
+* const BlogClient = makeStarlightClient({
+*   workspace: '123123123',
+*   debug: true
+* })
+*
+* // Feel free to export the new client so your application can use it.
+* export default BlogClient
+* ```
+*
+* @param config The client configuration object. You need to provide at least
+* the `workspace` property. See {@link StarlightConfig} to view all the
+* available options.
+* @group Client
+*/
+function makeClient(config = {}) {
+	let baseUrl = config.baseUrl ?? "https://query.starlightcms.io/v2";
+	let workspace = config.workspace ?? "";
+	let debug = config.debug ?? false;
+	return new Proxy({
+		configure(config) {
+			baseUrl = config.baseUrl ?? baseUrl;
+			workspace = config.workspace ?? workspace;
+			debug = config.debug ?? debug;
+		},
+		log(message, ...optionalParams) {
+			if (debug) console.log(message, ...optionalParams);
+		},
+		getBaseUrl() {
+			if (!workspace.length) throw new Error("No workspace defined. Use the `configure()` method on the Starlight client to define one.");
+			return `${baseUrl}/workspaces/${workspace}`;
+		},
+		async get(path, params = {}, options) {
+			const filteredParams = Object.keys(params).reduce((accumulator, key) => {
+				const param = params[key];
+				if (param || param === false || param === 0) accumulator[key] = String(param);
+				return accumulator;
+			}, {});
+			const searchParams = new URLSearchParams(filteredParams).toString();
+			const finalPath = searchParams ? `${path}?${searchParams}` : path;
+			this.log(`Starlight - GET ${finalPath}`);
+			const response = await fetch(`${this.getBaseUrl()}${finalPath}`, options);
+			if (response.status >= 200 && response.status < 300) return await response.json();
+			else throw new StarlightError(`Starlight - GET ${path} returned ${response.status}: ${response.statusText}`, response);
+		},
+		get models() {
+			return makeModelSelector(this);
+		},
+		model(slug) {
+			return makeModelInstance(this, slug);
+		},
+		get forms() {
+			return makeFormSelector(this);
+		},
+		form(slug) {
+			return makeFormInstance(this, String(slug));
+		},
+		get singletons() {
+			return makeSingletonSelector(this);
+		},
+		get collections() {
+			return makeCollectionSelector(this);
+		},
+		collection(slug) {
+			return makeCollectionInstance(this, slug);
+		},
+		get media() {
+			return makeMediaSelector(this);
+		},
+		get search() {
+			return makeSearchSelector(this);
+		}
+	}, { get(target, prop) {
+		if (typeof prop === "string" && !Reflect.has(target, prop)) return makeModelInstance(target, prop);
+		return Reflect.get(target, prop);
+	} });
+}
+//#endregion
+//#region src/utils/image.ts
+/**
+* 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) => {
+	return media.files.find((file) => file.variation === "optimized") ?? 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) => {
+	if (!media) return void 0;
+	if (variation) {
+		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);
+};
+/**
+* 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 ? getMediaFile(media, variation).path : void 0;
+}
+//#endregion
+//#region src/index.ts
+/**
+* This is the default object exported by the SDK module, which is a
+* pre-created {@link StarlightClient}. In the docs, this is called the "global
+* SDK client". If your application only requests data from a single Starlight
+* workspace, using this client is easier than creating
+* a new one using {@link makeStarlightClient}.
+*
+* Using the default client is as easy as importing the SDK:
+*
+* ```ts
+* // "Starlight" below is the default client.
+* import Starlight from '@starlightcms/js-sdk'
+*
+* const response = await Starlight.posts.entries.list()
+* ```
+*
+* You need to configure the default workspace before using it.
+* See {@apilink StarlightClient.configure} to learn more.
+*
+* @group Client
+*/
+const Starlight = makeClient();
+//#endregion
+exports.StarlightError = StarlightError;
+exports.default = Starlight;
+exports.getMediaFile = getMediaFile;
+exports.getMediaSource = getMediaSource;
+exports.makeStarlightClient = makeClient;