@sume-com/client 0.0.0-stage → 0.3.0

package/dist/v2/client.js

@@ -0,0 +1,379 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSumeClient = createSumeClient;
+exports.configure = configure;
+exports.reset = reset;
+const axios_1 = __importDefault(require("axios"));
+const crypto_1 = require("crypto");
+const config_1 = require("../config");
+const auth_1 = require("../auth");
+const errors_1 = require("../errors");
+const retry_1 = require("../utils/retry");
+const version_1 = require("../version");
+const globalState = {};
+const TERMINAL_STATUSES = new Set([
+    'completed',
+    'failed',
+    'canceled',
+]);
+const IDEMPOTENCY_KEY = /^[\x20-\x7E]{1,255}$/;
+const MODEL_ID = /^[A-Za-z0-9][\w.-]*$/;
+const ROUTER_BY_KIND = {
+    image: '/v1/image-router/generate',
+    video: '/v1/video-router/generate',
+    lipsync: '/v1/video-router/generate',
+    captions: '/v1/video-router/generate',
+};
+function checkBrowserEnvironment() {
+    const isBrowser = typeof globalThis.window !== 'undefined';
+    if (isBrowser) {
+        throw new errors_1.BrowserNotSupportedError();
+    }
+}
+function parseApiKey(value) {
+    const key = value.trim();
+    if (key === '' || /\s|:/.test(key)) {
+        throw new errors_1.BadInputError('Credentials must be one Sume API key ("sume_live_..."), not "KEY_ID:KEY_SECRET"');
+    }
+    return key;
+}
+function validationDetail(body) {
+    const errors = body?.details?.errors;
+    if (!Array.isArray(errors) || errors.length === 0) {
+        return undefined;
+    }
+    return errors.map((err) => ({
+        type: String(err?.type ?? 'invalid'),
+        loc: Array.isArray(err?.loc)
+            ? err.loc.map(String)
+            : typeof err?.path === 'string' && err.path !== ''
+                ? err.path.split('.')
+                : [],
+        msg: String(err?.message ?? err?.msg ?? 'Invalid value'),
+    }));
+}
+function mapAPIError(error) {
+    const response = error.response;
+    if (!response) {
+        const wrapped = new errors_1.APIError(`Request to the Sume API failed: ${error.message}`);
+        wrapped.code = error.code;
+        throw wrapped;
+    }
+    const data = response.data;
+    const body = data && typeof data === 'object' ? data.error : undefined;
+    const message = typeof body?.message === 'string' && body.message !== '' ? body.message : error.message;
+    if (response.status === 401) {
+        throw new errors_1.AuthenticationError(message, data);
+    }
+    else if (response.status === 402) {
+        throw new errors_1.NotEnoughCreditsError(message, data);
+    }
+    else if (response.status === 422) {
+        throw new errors_1.ValidationError(validationDetail(body) ?? message, data);
+    }
+    else if (response.status === 400) {
+        throw new errors_1.BadInputError(validationDetail(body) ?? message, data);
+    }
+    throw new errors_1.APIError(message, response.status, data, (0, retry_1.parseRetryAfter)(response.headers?.['retry-after']));
+}
+function mapStorageError(error) {
+    const status = error.response?.status;
+    const wrapped = new errors_1.APIError(status
+        ? `Upload to storage failed with status ${status}`
+        : `Upload to storage failed: ${error.message}`, status, undefined, (0, retry_1.parseRetryAfter)(error.response?.headers?.['retry-after']));
+    if (!status) {
+        wrapped.code = error.code;
+    }
+    throw wrapped;
+}
+function initializeClient(config) {
+    checkBrowserEnvironment();
+    let apiKey;
+    if (config?.credentials) {
+        apiKey = parseApiKey(config.credentials);
+    }
+    else if (config?.apiKey) {
+        apiKey = parseApiKey(config.apiKey);
+    }
+    const cfg = new config_1.Config(config);
+    let creds;
+    if (apiKey) {
+        creds = { apiKey };
+    }
+    else {
+        try {
+            creds = (0, auth_1.fetchCredentials)();
+        }
+        catch {
+            creds = { apiKey: '' };
+        }
+    }
+    const headers = {
+        Authorization: `Bearer ${creds.apiKey}`,
+        'Content-Type': 'application/json',
+    };
+    if (typeof process !== 'undefined' && process.versions?.node) {
+        headers['User-Agent'] = `sume-server-js/${version_1.VERSION}`;
+    }
+    Object.assign(headers, cfg.headers);
+    const axiosClient = axios_1.default.create({
+        baseURL: cfg.baseURL,
+        timeout: cfg.timeout,
+        headers,
+    });
+    axiosClient.interceptors.response.use((response) => response, mapAPIError);
+    return { config: cfg, client: axiosClient, credentials: creds, routes: new Map() };
+}
+function retryConfig(config) {
+    return {
+        maxRetries: config.maxRetries,
+        backoff: config.retryBackoff,
+        maxBackoff: config.retryMaxBackoff,
+    };
+}
+function unwrap(body) {
+    return body && typeof body === 'object' && body.data && typeof body.data === 'object'
+        ? body.data
+        : body;
+}
+function requestIdOf(payload) {
+    const id = payload?.request_id ?? payload?.job_id ?? payload?.job?.id;
+    if (typeof id !== 'string' || id === '') {
+        throw new errors_1.APIError('The Sume API answered without a request id', undefined, payload);
+    }
+    return id;
+}
+function statusOf(payload) {
+    const raw = payload?.sume_status ?? payload?.job?.status ?? payload?.status;
+    switch (String(raw ?? '').toLowerCase()) {
+        case 'queued':
+        case 'in_queue':
+            return 'queued';
+        case 'processing':
+        case 'in_progress':
+            return 'in_progress';
+        case 'completed':
+            return 'completed';
+        case 'failed':
+            return 'failed';
+        case 'canceled':
+        case 'cancelled':
+            return 'canceled';
+        default:
+            return payload?.terminal === true ? 'failed' : 'in_progress';
+    }
+}
+function isTerminal(payload) {
+    return payload?.terminal === true || TERMINAL_STATUSES.has(statusOf(payload));
+}
+function jobPath(requestId, suffix = '') {
+    return `/v1/jobs/${encodeURIComponent(requestId)}${suffix}`;
+}
+function jobUrl(config, requestId, suffix) {
+    return `${config.baseURL.replace(/\/+$/, '')}${jobPath(requestId, suffix)}`;
+}
+function nextPollDelay(config, payload) {
+    const hint = Number(payload?.next_poll_after_seconds);
+    return Math.max(config.pollInterval, Number.isFinite(hint) && hint > 0 ? hint * 1000 : 0);
+}
+function toV2Response(config, payload, artifacts, error) {
+    const requestId = requestIdOf(payload);
+    const status = statusOf(payload);
+    const response = {
+        status: status === 'failed' && error?.public_reason === 'content_policy_rejected' ? 'nsfw' : status,
+        request_id: requestId,
+        status_url: payload.status_url ?? jobUrl(config, requestId, '/status'),
+        cancel_url: payload.cancel_url ?? null,
+        result_url: payload.result_url ?? jobUrl(config, requestId, '/result'),
+    };
+    if (artifacts) {
+        const images = artifacts.filter((a) => a.type === 'image').map((a) => ({ url: a.url }));
+        const video = artifacts.find((a) => a.type === 'video');
+        if (images.length > 0) {
+            response.images = images;
+        }
+        if (video) {
+            response.video = { url: video.url };
+        }
+        response.artifacts = artifacts;
+    }
+    if (error !== undefined) {
+        response.error = error;
+    }
+    return response;
+}
+async function pollV2Request(client, config, submitted, idempotencyKey) {
+    const requestId = requestIdOf(submitted);
+    const pollingUrl = jobPath(requestId, '/status');
+    const deadline = Date.now() + config.maxPollTime;
+    let delay = nextPollDelay(config, submitted);
+    while (true) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            throw new errors_1.TimeoutError(`Polling exceeded maximum time of ${config.maxPollTime}ms for request ${requestId}. ` +
+                `The job keeps running: call subscribe again with idempotencyKey "${idempotencyKey}" to keep waiting for it.`, requestId, idempotencyKey);
+        }
+        await (0, retry_1.sleep)(Math.min(delay, remaining));
+        try {
+            const response = await client.get(pollingUrl);
+            const payload = unwrap(response.data);
+            if (isTerminal(payload)) {
+                return payload;
+            }
+            delay = nextPollDelay(config, payload);
+        }
+        catch (error) {
+            if (!(0, retry_1.isRetryableError)(error)) {
+                throw error;
+            }
+            delay = Math.max(config.pollInterval, (0, retry_1.retryAfterMs)(error) ?? 0);
+        }
+    }
+}
+async function finishRequest(client, config, payload) {
+    const requestId = requestIdOf(payload);
+    if (statusOf(payload) === 'completed') {
+        const response = await (0, retry_1.retryWithBackoff)(() => client.get(jobPath(requestId, '/result')), retryConfig(config));
+        const artifacts = unwrap(response.data)?.result?.artifacts;
+        return toV2Response(config, payload, Array.isArray(artifacts) ? artifacts : []);
+    }
+    let error = payload.job && typeof payload.job === 'object' && 'error' in payload.job
+        ? payload.job.error
+        : payload.error;
+    if (error === undefined) {
+        const response = await (0, retry_1.retryWithBackoff)(() => client.get(jobPath(requestId)), retryConfig(config));
+        error = unwrap(response.data)?.job?.error ?? null;
+    }
+    return toV2Response(config, payload, undefined, error);
+}
+async function resolveEndpoint(state, endpoint) {
+    if (endpoint.includes('/')) {
+        return { path: endpoint.startsWith('/') ? endpoint : `/${endpoint}` };
+    }
+    if (!MODEL_ID.test(endpoint)) {
+        throw new errors_1.BadInputError('Endpoint must be a model id, such as "gpt-image-2", or a path, such as "/v1/image-router/generate"');
+    }
+    const cached = state.routes?.get(endpoint);
+    if (cached) {
+        return { path: cached, model: endpoint };
+    }
+    const response = await (0, retry_1.retryWithBackoff)(() => state.client.get(`/v1/open/catalog/${encodeURIComponent(endpoint)}`), retryConfig(state.config));
+    const kind = unwrap(response.data)?.kind;
+    const path = typeof kind === 'string' ? ROUTER_BY_KIND[kind] : undefined;
+    if (!path) {
+        throw new errors_1.BadInputError(`Model "${endpoint}" is of kind "${String(kind)}", which this SDK cannot route. ` +
+            `Call subscribe('/v1/<router>/generate', { input: { model: '${endpoint}', ... } }).`);
+    }
+    (state.routes ?? (state.routes = new Map())).set(endpoint, path);
+    return { path, model: endpoint };
+}
+function toBuffer(data) {
+    if (Buffer.isBuffer(data)) {
+        return data;
+    }
+    if (data instanceof Uint8Array) {
+        return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    }
+    throw new errors_1.BadInputError('Upload data must be a Buffer or Uint8Array');
+}
+function createSumeClient(config) {
+    const state = config ? initializeClient(config) : globalState;
+    function ensureInitialized() {
+        checkBrowserEnvironment();
+        if (!state.client || !state.credentials?.apiKey) {
+            const initialized = initializeClient(state.config);
+            if (!initialized.credentials.apiKey) {
+                throw new errors_1.CredentialsMissedError();
+            }
+            Object.assign(state, initialized);
+        }
+    }
+    async function upload(data, contentType) {
+        ensureInitialized();
+        const client = state.client;
+        const clientConfig = state.config;
+        if (typeof contentType !== 'string' || contentType.trim() === '') {
+            throw new errors_1.BadInputError('Content type must be a MIME type, such as "image/png"');
+        }
+        const bytes = toBuffer(data);
+        if (bytes.byteLength === 0) {
+            throw new errors_1.BadInputError('Upload data is empty');
+        }
+        const linkResponse = await (0, retry_1.retryWithBackoff)(() => client.post('/v1/files/generate-upload-url', {
+            content_type: contentType,
+            size_bytes: bytes.byteLength,
+        }), retryConfig(clientConfig));
+        const link = unwrap(linkResponse.data);
+        const storage = axios_1.default.create();
+        storage.interceptors.response.use((response) => response, mapStorageError);
+        await (0, retry_1.retryWithBackoff)(() => storage.request({
+            method: link.upload_method || 'PUT',
+            url: link.upload_url,
+            data: bytes,
+            headers: link.upload_headers ?? { 'Content-Type': link.content_type ?? contentType },
+            maxBodyLength: Infinity,
+            maxContentLength: Infinity,
+            timeout: clientConfig.timeout,
+        }), retryConfig(clientConfig));
+        return link.public_url;
+    }
+    return {
+        async subscribe(endpoint, options) {
+            ensureInitialized();
+            const client = state.client;
+            const clientConfig = state.config;
+            if (typeof endpoint !== 'string' || endpoint.trim() === '') {
+                throw new errors_1.BadInputError('Endpoint must be a model id, such as "gpt-image-2", or a path, such as "/v1/image-router/generate"');
+            }
+            if (!options || typeof options.input !== 'object' || options.input === null) {
+                throw new errors_1.BadInputError('options.input must be an object');
+            }
+            const inputModel = options.input.model;
+            if (!endpoint.includes('/') && inputModel !== undefined && inputModel !== endpoint) {
+                throw new errors_1.BadInputError(`input.model "${String(inputModel)}" does not match the endpoint model "${endpoint}"`);
+            }
+            const { input, webhook, withPolling = true } = options;
+            const idempotencyKey = options.idempotencyKey ?? (0, crypto_1.randomUUID)();
+            if (!IDEMPOTENCY_KEY.test(idempotencyKey)) {
+                throw new errors_1.BadInputError('idempotencyKey must be 1 to 255 printable ASCII characters');
+            }
+            const { path, model } = await resolveEndpoint(state, endpoint);
+            const requestBody = model ? { ...input, model } : { ...input };
+            if (webhook) {
+                requestBody.mode = 'webhook';
+                requestBody.webhook_url = webhook.url;
+            }
+            const response = await (0, retry_1.retryWithBackoff)(() => client.post(path, requestBody, {
+                headers: { 'Idempotency-Key': idempotencyKey },
+            }), retryConfig(clientConfig));
+            let payload = unwrap(response.data);
+            if (!isTerminal(payload)) {
+                if (!withPolling) {
+                    return toV2Response(clientConfig, payload);
+                }
+                payload = await pollV2Request(client, clientConfig, payload, idempotencyKey);
+            }
+            return finishRequest(client, clientConfig, payload);
+        },
+        upload,
+        async uploadImage(imageBuffer, format = 'jpeg') {
+            return upload(imageBuffer, `image/${format}`);
+        },
+        configure(config) {
+            checkBrowserEnvironment();
+            Object.assign(state, initializeClient(config));
+        },
+    };
+}
+function configure(config) {
+    Object.assign(globalState, initializeClient(config));
+}
+function reset() {
+    globalState.config = undefined;
+    globalState.client = undefined;
+    globalState.credentials = undefined;
+    globalState.routes = undefined;
+}

package/dist/v2/index.d.ts

@@ -0,0 +1,12 @@
+import { createSumeClient, configure as configureClient, V2ClientConfig, SumeClient, SubscribeOptions, SubscribeInput } from './client';
+export declare const sume: SumeClient;
+export declare function config(config: V2ClientConfig): void;
+export { configureClient as configure, createSumeClient };
+export type { V2ClientConfig, SumeClient, SubscribeOptions, SubscribeInput };
+export type { ClientConfig } from '../config';
+export { DEFAULT_BASE_URL } from '../config';
+export { VERSION } from '../version';
+export * from '../types';
+export * from '../errors';
+export * from '../helpers';
+export * from './types';

package/dist/v2/index.js

@@ -0,0 +1,33 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = exports.DEFAULT_BASE_URL = exports.createSumeClient = exports.configure = exports.sume = void 0;
+exports.config = config;
+const client_1 = require("./client");
+Object.defineProperty(exports, "createSumeClient", { enumerable: true, get: function () { return client_1.createSumeClient; } });
+Object.defineProperty(exports, "configure", { enumerable: true, get: function () { return client_1.configure; } });
+exports.sume = (0, client_1.createSumeClient)(undefined);
+function config(config) {
+    (0, client_1.configure)(config);
+}
+var config_1 = require("../config");
+Object.defineProperty(exports, "DEFAULT_BASE_URL", { enumerable: true, get: function () { return config_1.DEFAULT_BASE_URL; } });
+var version_1 = require("../version");
+Object.defineProperty(exports, "VERSION", { enumerable: true, get: function () { return version_1.VERSION; } });
+__exportStar(require("../types"), exports);
+__exportStar(require("../errors"), exports);
+__exportStar(require("../helpers"), exports);
+__exportStar(require("./types"), exports);

package/dist/v2/types.d.ts

@@ -0,0 +1,58 @@
+import { Artifact, JobError } from '../types';
+export interface ImageGenerateInput {
+    model: string;
+    prompt: string;
+    image_urls?: string[];
+    aspect_ratio?: string;
+    image_size?: string | {
+        width: number;
+        height: number;
+    };
+    quality?: string;
+    resolution?: string;
+    num_images?: number;
+    output_format?: 'png' | 'jpeg' | 'webp';
+    mask_url?: string;
+    metadata?: Record<string, unknown>;
+    [field: string]: unknown;
+}
+export interface VideoGenerateInput {
+    model: string;
+    prompt?: string;
+    duration?: number;
+    resolution?: string;
+    aspect_ratio?: string;
+    image_url?: string;
+    end_image_url?: string;
+    video_url?: string;
+    audio_url?: string;
+    reference_image_urls?: string[];
+    reference_video_urls?: string[];
+    reference_audio_urls?: string[];
+    generate_audio?: boolean;
+    metadata?: Record<string, unknown>;
+    [field: string]: unknown;
+}
+export interface EndpointInputMap {
+    '/v1/image-router/generate': ImageGenerateInput;
+    '/v1/video-router/generate': VideoGenerateInput;
+}
+export type EndpointInput<TEndpoint extends keyof EndpointInputMap> = EndpointInputMap[TEndpoint];
+export type V2RequestStatus = 'queued' | 'in_progress' | 'completed' | 'failed' | 'nsfw' | 'canceled';
+export interface V2Image {
+    url: string;
+}
+export interface V2Video {
+    url: string;
+}
+export interface V2Response {
+    status: V2RequestStatus;
+    request_id: string;
+    status_url: string;
+    cancel_url: string | null;
+    result_url: string;
+    images?: V2Image[];
+    video?: V2Video;
+    artifacts?: Artifact[];
+    error?: JobError | null;
+}

package/dist/v2/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.3.0";

package/dist/version.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+exports.VERSION = '0.3.0';

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "@sume-com/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Official Sume SDK for Node.js and TypeScript",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./v2": {
+      "types": "./dist/v2/index.d.ts",
+      "default": "./dist/v2/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "v2": [
+        "./dist/v2/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.txt"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "build:prod": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.prod.json",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch --passWithNoTests",
+    "lint": "eslint src",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "prepare": "npm run build:prod",
+    "prepublishOnly": "npm run build:prod && npm run test"
+  },
+  "keywords": [
+    "sume",
+    "open.sume.com",
+    "ai",
+    "api",
+    "client",
+    "sdk",
+    "typescript",
+    "image-generation",
+    "video-generation"
+  ],
+  "author": "Sume Labs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sumelabs/sume-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sumelabs/sume-js/issues"
+  },
+  "homepage": "https://open.sume.com/docs",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.20.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.19.0",
+    "eslint": "^10.13.0",
+    "jest": "^30.5.2",
+    "prettier": "^3.9.10",
+    "ts-jest": "^29.4.15",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.72.0"
+  }
+}