@kittl/sdk 0.0.8 → 1.0.0-alpha.1

package/dist/sharedFileBrowser/sdk.d.ts

@@ -0,0 +1,328 @@
+declare class SdkBadInputError extends Error {
+	readonly name: "SdkBadInputError";
+	readonly cause?: Error;
+	constructor(message: string, cause?: Error);
+}
+declare class SdkInternalError extends Error {
+	readonly name: "SdkInternalError";
+	readonly cause?: Error;
+	constructor(message: string, cause?: Error);
+}
+declare const UploadType: {
+	readonly EXTENSION: "EXTENSION";
+	readonly AI_GENERATED: "AI_GENERATED";
+	readonly AI_GENERATED_SETS: "AI_GENERATED_SETS";
+	readonly AI_UPSCALED: "AI_UPSCALED";
+	readonly AI_EDITED: "AI_EDITED";
+	readonly MOCKUP: "MOCKUP";
+	readonly CLIPPED: "CLIPPED";
+	readonly BRAND_KIT: "BRAND_KIT";
+	readonly QUICK_EDIT: "QUICK_EDIT";
+};
+export declare const kittl: SharedFileBrowserKittlSDK;
+/**
+ * Unwraps an {@link SdkResult}, returning its value on success and throwing its
+ * error on failure. This lets callers use regular `try`/`catch` control flow
+ * around direct SDK calls instead of branching on `isOk` every time — branching
+ * on `isOk` directly remains fully supported.
+ *
+ * @typeParam T - The success value type carried by the result.
+ * @param result - The {@link SdkResult} returned by an SDK call.
+ * @returns The success value when `result.isOk` is `true`.
+ * @throws The result's `error` when `result.isOk` is `false`.
+ *
+ * @example
+ * ```typescript
+ * import { kittl, unwrapResult } from '@kittl/sdk/editorContentPanel';
+ *
+ * try {
+ *   const image = unwrapResult(await kittl.project.design.api.image.addImage(params));
+ *   console.log('Added image:', image.id);
+ * } catch (error) {
+ *   console.error('Failed to add image:', error);
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function unwrapResult<T>(result: SdkResult<T, Error>): T;
+export interface AsyncAuthAPI {
+	startAuth: (request: AuthStartRequest) => Promise<SdkResult<AuthStartResult>>;
+	exchangeCode: (request: AuthExchangeRequest) => Promise<SdkResult<AuthTokenResponse>>;
+	getAuthToken: (request: AuthGetTokenRequest) => Promise<SdkResult<AuthTokenResponse | null>>;
+	refreshToken: (request: AuthRefreshRequest) => Promise<SdkResult<AuthTokenResponse>>;
+	getUserToken: () => Promise<SdkResult<UserTokenResult>>;
+	logout: (request: AuthLogoutRequest) => Promise<SdkResult<void>>;
+}
+export interface AuthExchangeRequest {
+	code: string;
+	code_verifier?: string;
+	provider: string;
+	params?: Record<string, unknown>;
+	headers?: Record<string, string>;
+}
+export interface AuthGetTokenRequest {
+	provider: string;
+}
+export interface AuthLogoutRequest {
+	provider?: string;
+}
+export interface AuthRefreshRequest {
+	provider: string;
+}
+export interface AuthStartRequest {
+	provider: string;
+	params?: Record<string, string | number | boolean>;
+	generatePKCE?: boolean;
+}
+export interface AuthStartResult {
+	code: string;
+	code_verifier?: string;
+}
+/**
+ * Token response returned by the token endpoint (code exchange or refresh).
+ */
+export interface AuthTokenResponse {
+	access_token?: string;
+	refresh_token?: string;
+	expires_in?: number;
+	[key: string]: unknown;
+}
+/** Historical registration surface retained for existing extensions. */
+export interface FileBrowserAPI {
+	/** @deprecated Use context.registerUploadBrowser on the sharedFileBrowser entrypoint. */
+	registerUploadBrowser: UploadBrowserRegistrationAPI["registerUploadBrowser"];
+}
+/**
+ * File browser registration API exposed to content panels and shared file browsers.
+ *
+ * @public
+ */
+export interface KittlSDKFileBrowserAPI {
+	/**
+	 * File browser API for registering custom file browser tabs in the upload modal.
+	 * Allows extensions to provide custom content sources that appear as tabs in the upload gallery.
+	 */
+	fileBrowser: FileBrowserAPI;
+}
+/**
+ * Lifecycle fields shared by every public SDK mounting point.
+ *
+ * @public
+ */
+export interface KittlSDKLifecycle {
+	/**
+	 * Whether the SDK is loaded and has called the onLoadedCallback.
+	 */
+	loaded: boolean;
+	/**
+	 * Callback function called when the extension is loaded.
+	 */
+	onLoadedCallback: (() => void) | null;
+	/**
+	 * Sets a callback to be called when the extension is ready.
+	 */
+	onReady: (cb: () => void) => void;
+}
+/**
+ * Host-agnostic APIs every mounting-point SDK entrypoint exposes.
+ *
+ * @public
+ */
+export interface KittlSDKSharedAPIs {
+	/**
+	 * Auth API for extension OAuth flows via the host page.
+	 */
+	auth: AsyncAuthAPI;
+}
+/** Registers an extension-owned content source using the existing callback protocol. */
+export interface UploadBrowserRegistrationAPI {
+	/** Registers a tab whose fetchContent callback remains inside this iframe. */
+	registerUploadBrowser: (tab: Omit<FileBrowserTab, "onEvent">) => Promise<SdkResponse<void>>;
+}
+export interface UserTokenResult {
+	success: true;
+	token: string;
+}
+/**
+ * Union of nodes a dynamic tab can return.
+ */
+export type FileBrowserContent = FileBrowserItem | FileBrowserFolder;
+/**
+ * Input arguments for a file browser content request.
+ */
+export type FileBrowserFetchContentParams = {
+	/** Folder or entry id to load. Omit to load the root content. */
+	id?: string;
+	/** Optional pagination cursor for fetching the next slice of content. */
+	next?: string | number;
+	/**
+	 * Media kinds the current session accepts, so a tab backed by an API that
+	 * can filter server-side does not spend a page on entries the gallery will
+	 * hide anyway.
+	 *
+	 * This is an optimisation hint, not a contract: the host still drops
+	 * entries of an unwanted kind before rendering, so a tab that ignores this
+	 * stays correct. `undefined` means the session did not narrow its kinds.
+	 */
+	formats?: readonly FileBrowserMediaFormat[];
+};
+/**
+ * Result returned from a file browser content request.
+ */
+export type FileBrowserFetchContentResult = {
+	/** Content nodes returned for the requested folder or root view. */
+	content: FileBrowserContent[];
+	/** Optional cursor for loading the next page of the same folder view. */
+	next?: string | number;
+	error?: string;
+};
+/**
+ * Nested folder node returned by a dynamic gallery tab.
+ */
+export type FileBrowserFolder = {
+	type: "folder";
+	label: string;
+	id: string;
+	preview?: string;
+	/**
+	 * Optional eager-loaded children for this folder.
+	 *
+	 * When omitted, consumers should call the tab's
+	 * `fetchContent({ id: folder.id })` method to load the folder contents on
+	 * demand.
+	 */
+	content?: Array<FileBrowserContent>;
+};
+/**
+ * Leaf asset returned by a dynamic gallery tab.
+ */
+export type FileBrowserItem = {
+	type: "item";
+	label: string;
+	id: string;
+	preview?: string;
+	/**
+	 * Optional looping preview played while the tile is hovered — e.g. an
+	 * animated WEBP or GIF of a video's opening seconds.
+	 *
+	 * Only used for video items, which fall back to their static `preview` when
+	 * this is omitted.
+	 */
+	animatedPreview?: string;
+	content: {
+		data: string;
+		/** Optional MIME type used when materializing the selected asset. */
+		mimeType?: string;
+		/** Persisted upload classification. */
+		uploadType?: UploadType;
+	};
+};
+/**
+ * Media kind a file browser session can deal in.
+ *
+ * Both kinds are browsable and selectable; only images have an upload path.
+ */
+export type FileBrowserMediaFormat = "image" | "video";
+/**
+ * Registration contract for a file browser tab in the upload panel.
+ */
+export type FileBrowserTab = {
+	/** Unique identifier for the browser tab */
+	id: string;
+	/** Display label for the tab */
+	label: string;
+	/** Optional display order. Lower values render first. */
+	order?: number;
+	/** Optional product empty-state treatment. Omit for the generic state. */
+	emptyState?: FileBrowserTabEmptyState;
+	/**
+	 * Media kinds this tab is able to return.
+	 *
+	 * Unlike the `formats` hint handed to `fetchContent` — what the session
+	 * wants — this is what the tab has. The host hides the whole tab when the
+	 * two sets do not intersect, so a session that only wants video never opens
+	 * an image-only tab just to find it empty.
+	 *
+	 * Omit (or pass an empty array) when the tab can return any kind, or when it
+	 * cannot know in advance; such a tab is always shown and its entries are
+	 * filtered on render as before.
+	 */
+	supportedFormats?: readonly FileBrowserMediaFormat[];
+	/**
+	 * Loads root content, a specific folder, or a specific entry.
+	 *
+	 * If a returned folder has `content === undefined`, call
+	 * `fetchContent({ id: folder.id })` to load that folder lazily.
+	 *
+	 * If the returned result exposes `next`, pass it back as
+	 * `fetchContent({ id, next })` to load the next page for that folder view.
+	 *
+	 * The provider may also call `fetchContent({ id })` to refresh one specific
+	 * entry when invalidation is requested.
+	 */
+	fetchContent: (params?: FileBrowserFetchContentParams) => Promise<FileBrowserFetchContentResult>;
+	/** Optional lifecycle hook emitted by the host gallery. */
+	onEvent?: (event: FileBrowserTabEvent) => void;
+};
+/** Product empty-state treatment shown when a tab has no content. */
+export type FileBrowserTabEmptyState = "aiCreations" | "uploads";
+/** Lifecycle event emitted by the host gallery. */
+export type FileBrowserTabEvent = "close" | "open" | "upload";
+/**
+ * Unified SDK error type that encompasses all possible SDK errors.
+ * Use the `name` property to discriminate between error types.
+ *
+ * @public
+ */
+export type SdkError = SdkBadInputError | SdkInternalError;
+export type SdkResponse<T> = {
+	isOk: true;
+	result: T;
+} | {
+	isOk: false;
+	error: Error;
+};
+/**
+ * A result type that represents the result of a synchronous operation.
+ *
+ * This is the standard return type for sync SDK methods that can fail.
+ * It provides a type-safe way to handle both success and error cases without throwing.
+ *
+ * @typeParam T - The success value type
+ * @typeParam E - The error type
+ *
+ * @example
+ * ```typescript
+ * const result = someApi.syncOperation({ ... });
+ *
+ * if (result.isOk) {
+ *   console.log('Success:', result.result);
+ * } else {
+ *   console.error('Failed:', result.error.message);
+ * }
+ * ```
+ *
+ * @public
+ */
+export type SdkResult<T, E = SdkError> = {
+	isOk: true;
+	result: T;
+	error?: never;
+} | {
+	isOk: false;
+	result?: never;
+	error: E;
+};
+export type UploadType = (typeof UploadType)[keyof typeof UploadType];
+/** Public SDK shape for shared file browser extensions, which run hidden. */
+type SharedFileBrowserKittlSDK = KittlSDKLifecycle & KittlSDKSharedAPIs & {
+	/** Tab registration only: hidden file browsers get no host context. */
+	context: UploadBrowserRegistrationAPI;
+} & KittlSDKFileBrowserAPI;
+
+export {
+	SharedFileBrowserKittlSDK as KittlSDK,
+};
+
+export {};