@xmodeai/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,667 @@
+//#region src/core/errors.ts
+/** Base class for every error thrown by the SDK. */
+var XModeError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "XModeError";
+	}
+};
+/**
+* An error response from the API. The concrete subclass is chosen by the stable
+* `error.code` contract; an unrecognized code yields a plain `XModeAPIError`
+* (forward-compat — a new server code never crashes error handling).
+*/
+var XModeAPIError = class extends XModeError {
+	status;
+	code;
+	fields;
+	/** Value of the `X-XMode-Request-Id` response header, when present. */
+	requestId;
+	constructor(init) {
+		super(init.message);
+		this.name = "XModeAPIError";
+		this.status = init.status;
+		this.code = init.code;
+		this.fields = init.fields;
+		this.requestId = init.requestId;
+	}
+};
+/** 400 `validation_error` — request failed schema validation. `fields` lists offending paths. */
+var ValidationError = class extends XModeAPIError {
+	constructor(init) {
+		super(init);
+		this.name = "ValidationError";
+	}
+};
+/** 401 `unauthorized` — missing or invalid API key. */
+var AuthenticationError = class extends XModeAPIError {
+	constructor(init) {
+		super(init);
+		this.name = "AuthenticationError";
+	}
+};
+/** 403 `forbidden` / `account_blocked` — the action is not allowed. */
+var PermissionDeniedError = class extends XModeAPIError {
+	constructor(init) {
+		super(init);
+		this.name = "PermissionDeniedError";
+	}
+};
+/** 404 `not_found` — the resource does not exist (scoped to your account). */
+var NotFoundError = class extends XModeAPIError {
+	constructor(init) {
+		super(init);
+		this.name = "NotFoundError";
+	}
+};
+/** 409 `conflict` — e.g. deleting an end-user that still has pending generations. */
+var ConflictError = class extends XModeAPIError {
+	constructor(init) {
+		super(init);
+		this.name = "ConflictError";
+	}
+};
+/** 429 `rate_limited` — too many requests. `retryAfter` (seconds) set when provided. */
+var RateLimitError = class extends XModeAPIError {
+	retryAfter;
+	constructor(init) {
+		super(init);
+		this.name = "RateLimitError";
+		this.retryAfter = init.retryAfter;
+	}
+};
+/** 402 `payment_required` — insufficient xTokens balance. */
+var PaymentRequiredError = class extends XModeAPIError {
+	constructor(init) {
+		super(init);
+		this.name = "PaymentRequiredError";
+	}
+};
+/** 422 `content_policy` — the prompt or inputs were rejected by the content filter. */
+var ContentPolicyError = class extends XModeAPIError {
+	constructor(init) {
+		super(init);
+		this.name = "ContentPolicyError";
+	}
+};
+/** `provider_error` / `provider_timeout` — upstream generation failed; safe to retry. */
+var ProviderError = class extends XModeAPIError {
+	constructor(init) {
+		super(init);
+		this.name = "ProviderError";
+	}
+};
+/** `internal_error` — unexpected server-side failure. */
+var InternalServerError = class extends XModeAPIError {
+	constructor(init) {
+		super(init);
+		this.name = "InternalServerError";
+	}
+};
+/** A network-level failure (DNS, connection reset, fetch threw) before a response was received. */
+var APIConnectionError = class extends XModeError {
+	cause;
+	constructor(message = "Connection error", cause) {
+		super(message);
+		this.name = "APIConnectionError";
+		this.cause = cause;
+	}
+};
+/** The request exceeded the configured `timeout` before a response arrived. */
+var APIConnectionTimeoutError = class extends APIConnectionError {
+	constructor(message = "Request timed out") {
+		super(message);
+		this.name = "APIConnectionTimeoutError";
+	}
+};
+/** A `*.wait` / `*.createAndWait` poll did not reach a terminal status in time. */
+var XModePollTimeoutError = class extends XModeError {
+	/** The most recent record observed before the timeout. */
+	lastRecord;
+	constructor(message, lastRecord) {
+		super(message);
+		this.name = "XModePollTimeoutError";
+		this.lastRecord = lastRecord;
+	}
+};
+const CODE_TO_CLASS = {
+	validation_error: ValidationError,
+	unauthorized: AuthenticationError,
+	account_blocked: AuthenticationError,
+	forbidden: PermissionDeniedError,
+	not_found: NotFoundError,
+	conflict: ConflictError,
+	rate_limited: RateLimitError,
+	payment_required: PaymentRequiredError,
+	content_policy: ContentPolicyError,
+	provider_error: ProviderError,
+	provider_timeout: ProviderError,
+	internal_error: InternalServerError
+};
+function isErrorBody(value) {
+	return typeof value === "object" && value !== null && "error" in value && typeof value.error === "object" && value.error !== null;
+}
+/**
+* Build the right error instance from a non-2xx response. Tolerant: a non-JSON
+* body or an unknown `code` still yields a usable `XModeAPIError`, never a
+* secondary parse error.
+*/
+function castAPIError(status, body, rawText, requestId, retryAfter) {
+	let code = `http_${status}`;
+	let message = rawText || `Request failed with status ${status}`;
+	let fields;
+	if (isErrorBody(body)) {
+		const err = body.error;
+		if (typeof err.code === "string" && err.code) code = err.code;
+		if (typeof err.message === "string" && err.message) message = err.message;
+		if (err.fields && typeof err.fields === "object") fields = err.fields;
+	}
+	const init = {
+		status,
+		code,
+		message,
+		fields,
+		requestId,
+		retryAfter
+	};
+	const Cls = CODE_TO_CLASS[code];
+	if (Cls) return new Cls(init);
+	if (status === 429) return new RateLimitError(init);
+	if (status === 404) return new NotFoundError(init);
+	if (status === 401) return new AuthenticationError(init);
+	if (status === 403) return new PermissionDeniedError(init);
+	return new XModeAPIError(init);
+}
+//#endregion
+//#region src/core/retry.ts
+const MAX_BACKOFF_MS = 8e3;
+const RETRY_AFTER_CAP_MS = 6e4;
+/**
+* Parse a `Retry-After` header into milliseconds. Supports both the
+* delta-seconds form (`"3"`) and the HTTP-date form. Returns null when absent
+* or unparseable.
+*/
+function parseRetryAfterMs(header) {
+	if (!header) return null;
+	const seconds = Number(header);
+	if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+	const date = Date.parse(header);
+	if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+	return null;
+}
+/** Same as {@link parseRetryAfterMs} but in whole seconds, for `RateLimitError.retryAfter`. */
+function parseRetryAfterSeconds(header) {
+	const ms = parseRetryAfterMs(header);
+	return ms === null ? void 0 : Math.ceil(ms / 1e3);
+}
+/**
+* Exponential backoff with full jitter. `Retry-After`, when present, sets a
+* floor (capped at 60s) so we never retry sooner than the server asked.
+*/
+function backoffDelay(attempt, retryAfterHeader) {
+	const exp = Math.min(MAX_BACKOFF_MS, 500 * 2 ** attempt);
+	const jittered = exp / 2 + Math.random() * (exp / 2);
+	const retryAfter = parseRetryAfterMs(retryAfterHeader);
+	if (retryAfter !== null) return Math.min(RETRY_AFTER_CAP_MS, Math.max(retryAfter, jittered));
+	return jittered;
+}
+/** Promise-based sleep that rejects if the (optional) signal aborts. */
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(signal.reason ?? /* @__PURE__ */ new Error("Aborted"));
+			return;
+		}
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason ?? /* @__PURE__ */ new Error("Aborted"));
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+//#endregion
+//#region src/core/request.ts
+function defaultPolicy(method) {
+	return method === "GET" ? "idempotent" : "create";
+}
+function isRetryableStatus(status, policy) {
+	if (policy === "create") return status === 429;
+	return status === 408 || status === 429 || status >= 500;
+}
+function buildUrl(baseUrl, path, query) {
+	let url = baseUrl + path;
+	if (query) {
+		const params = new URLSearchParams();
+		for (const [key, value] of Object.entries(query)) if (value !== void 0) params.append(key, String(value));
+		const qs = params.toString();
+		if (qs) url += (url.includes("?") ? "&" : "?") + qs;
+	}
+	return url;
+}
+function buildHeaders(config, args) {
+	const headers = {
+		Authorization: `Bearer ${config.apiKey}`,
+		Accept: "application/json",
+		"User-Agent": config.userAgent,
+		...config.defaultHeaders,
+		...args.headers
+	};
+	if (args.body !== void 0) headers["Content-Type"] = "application/json";
+	return headers;
+}
+function combineSignals(user, timeout) {
+	if (!user) return timeout;
+	if (typeof AbortSignal.any === "function") return AbortSignal.any([user, timeout]);
+	const controller = new AbortController();
+	const relay = (s) => controller.abort(s.reason);
+	for (const s of [user, timeout]) if (s.aborted) relay(s);
+	else s.addEventListener("abort", () => relay(s), { once: true });
+	return controller.signal;
+}
+async function parseSuccessBody(res) {
+	if (res.status === 204) return void 0;
+	const text = await res.text();
+	if (!text) return void 0;
+	return JSON.parse(text);
+}
+function safeJsonParse(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+/**
+* Execute a single logical request, applying auth, timeout, the tolerant JSON
+* reader (responses are never schema-validated), and the retry loop.
+*/
+async function execute(config, args) {
+	const policy = args.policy ?? defaultPolicy(args.method);
+	const maxRetries = args.maxRetries ?? config.maxRetries;
+	const url = buildUrl(config.baseUrl, args.path, args.query);
+	const headers = buildHeaders(config, args);
+	const body = args.body === void 0 ? void 0 : JSON.stringify(args.body);
+	for (let attempt = 0;; attempt++) {
+		const timeoutSignal = AbortSignal.timeout(args.timeout ?? config.timeout);
+		let res;
+		try {
+			res = await config.fetch(url, {
+				method: args.method,
+				headers,
+				body,
+				signal: combineSignals(args.signal, timeoutSignal)
+			});
+		} catch (err) {
+			if (args.signal?.aborted) throw args.signal.reason instanceof Error ? args.signal.reason : new APIConnectionError("Request aborted", err);
+			if (policy === "idempotent" && attempt < maxRetries) {
+				await sleep(backoffDelay(attempt, null), args.signal);
+				continue;
+			}
+			if (timeoutSignal.aborted) throw new APIConnectionTimeoutError();
+			throw new APIConnectionError("Connection error", err);
+		}
+		const requestId = res.headers.get("x-xmode-request-id") ?? void 0;
+		if (res.ok) return await parseSuccessBody(res);
+		if (isRetryableStatus(res.status, policy) && attempt < maxRetries) {
+			await sleep(backoffDelay(attempt, res.headers.get("retry-after")), args.signal);
+			continue;
+		}
+		const rawText = await res.text().catch(() => "");
+		throw castAPIError(res.status, safeJsonParse(rawText), rawText, requestId, parseRetryAfterSeconds(res.headers.get("retry-after")));
+	}
+}
+//#endregion
+//#region src/core/pagination.ts
+/**
+* One page of a paginated list, plus the ability to fetch the next page and to
+* iterate every item across all pages with `for await`.
+*/
+var Page = class Page {
+	items;
+	page;
+	pageSize;
+	hasMore;
+	fetcher;
+	query;
+	constructor(data, fetcher, query) {
+		this.items = data.items;
+		this.page = data.page;
+		this.pageSize = data.pageSize;
+		this.hasMore = data.hasMore;
+		this.fetcher = fetcher;
+		this.query = query;
+	}
+	/** Fetch the next page, or `null` when there are no more. */
+	async getNextPage() {
+		if (!this.hasMore) return null;
+		const nextQuery = {
+			...this.query,
+			page: this.page + 1
+		};
+		return new Page(await this.fetcher(nextQuery), this.fetcher, nextQuery);
+	}
+	async *[Symbol.asyncIterator]() {
+		let current = this;
+		while (current) {
+			for (const item of current.items) yield item;
+			current = await current.getNextPage();
+		}
+	}
+};
+/**
+* The return type of `list()` methods. `await` it to get the first {@link Page};
+* `for await (... of ...)` it to stream every item across all pages.
+*/
+var PagePromise = class extends Promise {
+	static get [Symbol.species]() {
+		return Promise;
+	}
+	async *[Symbol.asyncIterator]() {
+		yield* await this;
+	}
+};
+/** Build a {@link PagePromise} from a thunk that loads the first page. */
+function makePagePromise(load) {
+	return new PagePromise((resolve, reject) => {
+		load().then(resolve, reject);
+	});
+}
+//#endregion
+//#region src/resources/balance.ts
+var Balance = class {
+	client;
+	constructor(client) {
+		this.client = client;
+	}
+	/** Current xTokens balance. */
+	get(options) {
+		return this.client.request({
+			method: "GET",
+			path: "/v1/balance",
+			policy: "idempotent",
+			...options
+		});
+	}
+	/** Paginated ledger of balance changes. `await` for one page, or `for await` for all. */
+	history(params = {}, options) {
+		const query = {
+			page: params.page,
+			pageSize: params.pageSize
+		};
+		const fetcher = (q) => this.client.request({
+			method: "GET",
+			path: "/v1/balance/history",
+			query: q,
+			policy: "idempotent",
+			...options
+		});
+		return makePagePromise(async () => new Page(await fetcher(query), fetcher, query));
+	}
+};
+//#endregion
+//#region src/resources/end-users.ts
+function toQuery$1(params) {
+	return {
+		page: params.page,
+		pageSize: params.pageSize,
+		blocked: params.blocked === void 0 ? void 0 : String(params.blocked),
+		email: params.email
+	};
+}
+var EndUsers = class {
+	client;
+	constructor(client) {
+		this.client = client;
+	}
+	/** List your downstream end-users. `await` for one page, or `for await` for all. */
+	list(params = {}, options) {
+		const query = toQuery$1(params);
+		const fetcher = (q) => this.client.request({
+			method: "GET",
+			path: "/v1/end-users",
+			query: q,
+			policy: "idempotent",
+			...options
+		});
+		return makePagePromise(async () => new Page(await fetcher(query), fetcher, query));
+	}
+	/** Block an end-user. New generations are refused; pending ones still finish. */
+	block(email, options) {
+		return this.client.request({
+			method: "POST",
+			path: `/v1/end-users/${encodeURIComponent(email)}/block`,
+			policy: "idempotent",
+			...options
+		});
+	}
+	/** Unblock a previously blocked end-user. */
+	unblock(email, options) {
+		return this.client.request({
+			method: "POST",
+			path: `/v1/end-users/${encodeURIComponent(email)}/unblock`,
+			policy: "idempotent",
+			...options
+		});
+	}
+	/**
+	* Delete an end-user and all their generations and stored media. Fails with a
+	* `ConflictError` (409) if the end-user still has pending generations.
+	*/
+	delete(email, options) {
+		return this.client.request({
+			method: "DELETE",
+			path: `/v1/end-users/${encodeURIComponent(email)}`,
+			policy: "idempotent",
+			...options
+		});
+	}
+};
+//#endregion
+//#region src/core/poll.ts
+const DEFAULT_POLL_INTERVAL_MS = 5e3;
+const DEFAULT_POLL_TIMEOUT_MS = 10 * 6e4;
+const TERMINAL_STATUSES = new Set([
+	"succeeded",
+	"failed",
+	"expired"
+]);
+/** True once a record reaches a status from which it will not change. */
+function isTerminal(record) {
+	return TERMINAL_STATUSES.has(record.status);
+}
+/**
+* Poll `fetchRecord` until it returns a terminal record, then resolve with it.
+*
+* Tolerant of statuses this SDK version does not know: anything outside the
+* terminal set is treated as "still in progress", so a server-added status
+* never aborts a wait. Throws {@link XModePollTimeoutError} (carrying the last
+* record seen) if the budget elapses first.
+*/
+async function pollUntilTerminal(fetchRecord, options = {}) {
+	const pollInterval = options.pollInterval ?? 5e3;
+	const timeout = options.timeout ?? 6e5;
+	const deadline = Date.now() + timeout;
+	for (;;) {
+		const record = await fetchRecord();
+		if (isTerminal(record)) return record;
+		if (Date.now() + pollInterval >= deadline) throw new XModePollTimeoutError(`Did not reach a terminal status within ${timeout}ms (last status: ${record.status}).`, record);
+		await sleep(pollInterval, options.signal);
+	}
+}
+//#endregion
+//#region src/resources/generations.ts
+function toQuery(params) {
+	return {
+		page: params.page,
+		pageSize: params.pageSize,
+		endUserEmail: params.endUserEmail,
+		status: params.status,
+		createdAfter: params.createdAfter
+	};
+}
+var Generations = class {
+	client;
+	constructor(client) {
+		this.client = client;
+	}
+	/** Enqueue an image generation. Resolves with the `queued` record (202). */
+	create(input, options) {
+		return this.client.request({
+			method: "POST",
+			path: "/v1/generations",
+			body: input,
+			policy: "create",
+			...options
+		});
+	}
+	/** Fetch the current state of a generation. */
+	get(requestId, options) {
+		return this.client.request({
+			method: "GET",
+			path: `/v1/generations/${encodeURIComponent(requestId)}`,
+			policy: "idempotent",
+			...options
+		});
+	}
+	/** List generations. `await` for the first page, or `for await` to stream all items. */
+	list(params = {}, options) {
+		const query = toQuery(params);
+		const fetcher = (q) => this.client.request({
+			method: "GET",
+			path: "/v1/generations",
+			query: q,
+			policy: "idempotent",
+			...options
+		});
+		return makePagePromise(async () => new Page(await fetcher(query), fetcher, query));
+	}
+	/** Create a generation and poll until it reaches a terminal status. */
+	async createAndWait(input, options) {
+		const queued = await this.create(input, { signal: options?.signal });
+		return this.wait(queued.requestId, options);
+	}
+	/** Poll an existing generation until it reaches a terminal status. */
+	wait(requestId, options) {
+		return pollUntilTerminal(() => this.get(requestId, { signal: options?.signal }), options);
+	}
+};
+//#endregion
+//#region src/resources/videos.ts
+const DEFAULT_VIDEO_TIMEOUT_MS = 20 * 6e4;
+var Videos = class {
+	client;
+	constructor(client) {
+		this.client = client;
+	}
+	/** Enqueue a video generation. Resolves with the `queued` record (202). */
+	create(input, options) {
+		return this.client.request({
+			method: "POST",
+			path: "/v1/videos",
+			body: input,
+			policy: "create",
+			...options
+		});
+	}
+	/** Fetch the current state of a video. */
+	get(requestId, options) {
+		return this.client.request({
+			method: "GET",
+			path: `/v1/videos/${encodeURIComponent(requestId)}`,
+			policy: "idempotent",
+			...options
+		});
+	}
+	/** Create a video and poll until it reaches a terminal status. */
+	async createAndWait(input, options) {
+		const queued = await this.create(input, { signal: options?.signal });
+		return this.wait(queued.requestId, options);
+	}
+	/** Poll an existing video until it reaches a terminal status. */
+	wait(requestId, options) {
+		return pollUntilTerminal(() => this.get(requestId, { signal: options?.signal }), {
+			...options,
+			timeout: options?.timeout ?? DEFAULT_VIDEO_TIMEOUT_MS
+		});
+	}
+};
+//#endregion
+//#region src/version.ts
+const VERSION = "0.1.0";
+//#endregion
+//#region src/client.ts
+const DEFAULT_BASE_URL = "https://api.xmode.ai";
+const DEFAULT_TIMEOUT_MS = 3e4;
+const DEFAULT_MAX_RETRIES = 2;
+function readEnv(key) {
+	return globalThis.process?.env?.[key];
+}
+function normalizeBaseUrl(url) {
+	return url.replace(/\/+$/, "");
+}
+/**
+* The xMode API client.
+*
+* ```ts
+* import XMode from '@xmodeai/sdk';
+* const client = new XMode({ apiKey: process.env.XMODE_API_KEY });
+* const result = await client.generations.createAndWait({
+*   endUserEmail: 'alice@your-product.com',
+*   model: 'xSD4.5',
+*   prompt: 'a red panda astronaut, studio lighting',
+* });
+* ```
+*/
+var XMode = class {
+	generations;
+	videos;
+	balance;
+	endUsers;
+	config;
+	constructor(options = {}) {
+		const apiKey = options.apiKey ?? readEnv("XMODE_API_KEY");
+		if (!apiKey) throw new XModeError("Missing API key. Pass `apiKey` to new XMode({ apiKey }) or set the XMODE_API_KEY environment variable.");
+		const fetchImpl = options.fetch ?? (typeof globalThis.fetch === "function" ? globalThis.fetch.bind(globalThis) : void 0);
+		if (!fetchImpl) throw new XModeError("No global fetch found. Use Node 18+, or pass a `fetch` implementation in the client options.");
+		this.config = {
+			apiKey,
+			baseUrl: normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL),
+			timeout: options.timeout ?? DEFAULT_TIMEOUT_MS,
+			maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
+			fetch: fetchImpl,
+			defaultHeaders: options.defaultHeaders ?? {},
+			userAgent: `xmode-sdk/${VERSION}`
+		};
+		this.generations = new Generations(this);
+		this.videos = new Videos(this);
+		this.balance = new Balance(this);
+		this.endUsers = new EndUsers(this);
+	}
+	/**
+	* Low-level escape hatch. Call any endpoint / pass any body before a typed
+	* method exists for it (e.g. a brand-new model parameter). Applies the same
+	* auth, retry and error handling as the typed resource methods.
+	*
+	* ```ts
+	* await client.request({
+	*   method: 'POST',
+	*   path: '/v1/videos',
+	*   body: { endUserEmail, model: 'xSV2.0', prompt, image, cameraMotion: 'orbit' },
+	* });
+	* ```
+	*/
+	request(args) {
+		return execute(this.config, args);
+	}
+};
+//#endregion
+//#region src/index.ts
+var src_default = XMode;
+//#endregion
+export { APIConnectionError, APIConnectionTimeoutError, AuthenticationError, ConflictError, ContentPolicyError, DEFAULT_POLL_INTERVAL_MS, DEFAULT_POLL_TIMEOUT_MS, InternalServerError, NotFoundError, Page, PagePromise, PaymentRequiredError, PermissionDeniedError, ProviderError, RateLimitError, VERSION, ValidationError, XMode, XModeAPIError, XModeError, XModePollTimeoutError, src_default as default, isTerminal, pollUntilTerminal };
+
+//# sourceMappingURL=index.js.map