@sume-com/client 0.0.0-stage → 0.3.0

package/dist/auth.d.ts

@@ -0,0 +1,4 @@
+export interface Credentials {
+    apiKey: string;
+}
+export declare function fetchCredentials(): Credentials;

package/dist/auth.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchCredentials = fetchCredentials;
+const errors_1 = require("./errors");
+function fetchCredentials() {
+    const apiKey = process.env.SUME_API_KEY?.trim();
+    if (apiKey) {
+        return { apiKey };
+    }
+    throw new errors_1.CredentialsMissedError();
+}

package/dist/config.d.ts

@@ -0,0 +1,23 @@
+export interface ClientConfig {
+    timeout?: number;
+    maxRetries?: number;
+    retryBackoff?: number;
+    retryMaxBackoff?: number;
+    pollInterval?: number;
+    maxPollTime?: number;
+    headers?: Record<string, string>;
+    baseURL?: string;
+}
+export declare const DEFAULT_BASE_URL = "https://api.open.sume.com";
+export declare class Config implements ClientConfig {
+    timeout: number;
+    maxRetries: number;
+    retryBackoff: number;
+    retryMaxBackoff: number;
+    pollInterval: number;
+    maxPollTime: number;
+    headers: Record<string, string>;
+    baseURL: string;
+    constructor(config?: Partial<ClientConfig>);
+    private validate;
+}

package/dist/config.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Config = exports.DEFAULT_BASE_URL = void 0;
+exports.DEFAULT_BASE_URL = 'https://api.open.sume.com';
+const CONFIG_KEYS = [
+    'timeout',
+    'maxRetries',
+    'retryBackoff',
+    'retryMaxBackoff',
+    'pollInterval',
+    'maxPollTime',
+    'headers',
+    'baseURL',
+];
+class Config {
+    constructor(config) {
+        this.timeout = 120000;
+        this.maxRetries = 3;
+        this.retryBackoff = 1000;
+        this.retryMaxBackoff = 60000;
+        this.pollInterval = 2000;
+        this.maxPollTime = 300000;
+        this.headers = {};
+        this.baseURL = exports.DEFAULT_BASE_URL;
+        if (config) {
+            for (const key of CONFIG_KEYS) {
+                if (config[key] !== undefined) {
+                    Object.assign(this, { [key]: config[key] });
+                }
+            }
+            this.headers = { ...this.headers };
+        }
+        this.validate();
+    }
+    validate() {
+        if (!(this.timeout > 0)) {
+            throw new Error('timeout must be positive');
+        }
+        if (!(this.maxRetries >= 0)) {
+            throw new Error('maxRetries must be non-negative');
+        }
+        if (this.maxRetries > 5) {
+            throw new Error('maxRetries cannot be greater than 5');
+        }
+        if (!(this.retryBackoff >= 0)) {
+            throw new Error('retryBackoff must be non-negative');
+        }
+        if (!(this.retryMaxBackoff >= 0)) {
+            throw new Error('retryMaxBackoff must be non-negative');
+        }
+        if (!(this.pollInterval > 0)) {
+            throw new Error('pollInterval must be positive');
+        }
+        if (!(this.maxPollTime > 0)) {
+            throw new Error('maxPollTime must be positive');
+        }
+        let url;
+        try {
+            url = new URL(this.baseURL);
+        }
+        catch {
+            throw new Error('baseURL must be an absolute URL');
+        }
+        if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+            throw new Error('baseURL must be an http(s) URL');
+        }
+    }
+}
+exports.Config = Config;

package/dist/errors.d.ts

@@ -0,0 +1,47 @@
+export declare class SumeError extends Error {
+    constructor(message: string);
+}
+export interface ValidationErrorDetail {
+    type: string;
+    loc: string[];
+    msg: string;
+    input?: any;
+    ctx?: Record<string, any>;
+}
+export declare class APIError extends SumeError {
+    statusCode?: number;
+    responseData?: any;
+    code?: string;
+    requestId?: string;
+    retryAfter?: number;
+    constructor(message: string, statusCode?: number, responseData?: any, retryAfter?: number);
+}
+export declare class AuthenticationError extends APIError {
+    statusCode: number;
+    constructor(message?: string, responseData?: any);
+}
+export declare class CredentialsMissedError extends SumeError {
+    constructor();
+}
+export declare class TimeoutError extends SumeError {
+    requestId?: string;
+    idempotencyKey?: string;
+    constructor(message: string, requestId?: string, idempotencyKey?: string);
+}
+export declare class NotEnoughCreditsError extends APIError {
+    statusCode: number;
+    constructor(message?: string, responseData?: any);
+}
+export declare class ValidationError extends APIError {
+    statusCode: number;
+    details?: ValidationErrorDetail[];
+    constructor(detail: string | ValidationErrorDetail[] | undefined, responseData?: any);
+}
+export declare class BadInputError extends APIError {
+    statusCode: number;
+    details?: ValidationErrorDetail[];
+    constructor(detail: string | ValidationErrorDetail[] | undefined, responseData?: any);
+}
+export declare class BrowserNotSupportedError extends SumeError {
+    constructor();
+}

package/dist/errors.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserNotSupportedError = exports.BadInputError = exports.ValidationError = exports.NotEnoughCreditsError = exports.TimeoutError = exports.CredentialsMissedError = exports.AuthenticationError = exports.APIError = exports.SumeError = void 0;
+class SumeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SumeError';
+    }
+}
+exports.SumeError = SumeError;
+class APIError extends SumeError {
+    constructor(message, statusCode, responseData, retryAfter) {
+        super(message);
+        this.name = 'APIError';
+        this.statusCode = statusCode;
+        this.responseData = responseData;
+        const body = responseData?.error;
+        this.code = typeof body?.code === 'string' ? body.code : undefined;
+        this.requestId = typeof body?.request_id === 'string' ? body.request_id : undefined;
+        this.retryAfter =
+            retryAfter ??
+                (typeof body?.retry_after_seconds === 'number' ? body.retry_after_seconds : undefined);
+    }
+}
+exports.APIError = APIError;
+class AuthenticationError extends APIError {
+    constructor(message = 'Authentication failed', responseData) {
+        super(message, 401, responseData);
+        this.statusCode = 401;
+        this.name = 'AuthenticationError';
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+class CredentialsMissedError extends SumeError {
+    constructor() {
+        super('API key not found. Set the SUME_API_KEY environment variable, or pass credentials (or apiKey) in config. Create a key at https://open.sume.com/api-keys.');
+        this.name = 'CredentialsMissedError';
+    }
+}
+exports.CredentialsMissedError = CredentialsMissedError;
+class TimeoutError extends SumeError {
+    constructor(message, requestId, idempotencyKey) {
+        super(message);
+        this.name = 'TimeoutError';
+        this.requestId = requestId;
+        this.idempotencyKey = idempotencyKey;
+    }
+}
+exports.TimeoutError = TimeoutError;
+class NotEnoughCreditsError extends APIError {
+    constructor(message = 'Not enough credits', responseData) {
+        super(message, 402, responseData);
+        this.statusCode = 402;
+        this.name = 'NotEnoughCreditsError';
+    }
+}
+exports.NotEnoughCreditsError = NotEnoughCreditsError;
+function detailMessage(detail) {
+    if (Array.isArray(detail)) {
+        return {
+            message: detail
+                .map((err) => (err.loc.length > 0 ? `${err.loc.join('.')}: ${err.msg}` : err.msg))
+                .join(', '),
+            details: detail,
+        };
+    }
+    if (typeof detail === 'string') {
+        return { message: detail };
+    }
+    return { message: 'Check your input params' };
+}
+class ValidationError extends APIError {
+    constructor(detail, responseData) {
+        const { message, details } = detailMessage(detail);
+        super(message, 422, responseData);
+        this.statusCode = 422;
+        this.name = 'ValidationError';
+        this.details = details;
+    }
+}
+exports.ValidationError = ValidationError;
+class BadInputError extends APIError {
+    constructor(detail, responseData) {
+        const { message, details } = detailMessage(detail);
+        super(message, 400, responseData);
+        this.statusCode = 400;
+        this.name = 'BadInputError';
+        this.details = details;
+    }
+}
+exports.BadInputError = BadInputError;
+class BrowserNotSupportedError extends SumeError {
+    constructor() {
+        super('This SDK is not supported in browser environments. Please use it in a Node.js environment.');
+        this.name = 'BrowserNotSupportedError';
+    }
+}
+exports.BrowserNotSupportedError = BrowserNotSupportedError;

package/dist/helpers.d.ts

@@ -0,0 +1,7 @@
+import { WebhookPayload } from './types';
+export declare const WEBHOOK_TOLERANCE_SECONDS = 300;
+export declare const WEBHOOK_SIGNATURE_VERSION = "sume-v1";
+export declare const WEBHOOK_TIMESTAMP_HEADER = "x-sume-webhook-timestamp";
+export declare const WEBHOOK_SIGNATURE_HEADER = "x-sume-webhook-signature";
+export declare function webhook(url: string): WebhookPayload;
+export declare function verifyWebhook(rawBody: string | Buffer, timestamp: string | string[] | undefined, signature: string | string[] | undefined, secret: string, toleranceSeconds?: number): boolean;

package/dist/helpers.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEBHOOK_SIGNATURE_HEADER = exports.WEBHOOK_TIMESTAMP_HEADER = exports.WEBHOOK_SIGNATURE_VERSION = exports.WEBHOOK_TOLERANCE_SECONDS = void 0;
+exports.webhook = webhook;
+exports.verifyWebhook = verifyWebhook;
+const crypto_1 = require("crypto");
+const errors_1 = require("./errors");
+exports.WEBHOOK_TOLERANCE_SECONDS = 300;
+exports.WEBHOOK_SIGNATURE_VERSION = 'sume-v1';
+exports.WEBHOOK_TIMESTAMP_HEADER = 'x-sume-webhook-timestamp';
+exports.WEBHOOK_SIGNATURE_HEADER = 'x-sume-webhook-signature';
+function webhook(url) {
+    if (!url || typeof url !== 'string' || url.trim() === '') {
+        throw new errors_1.BadInputError('Webhook URL must be a non-empty string');
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new errors_1.BadInputError('Webhook URL must be an absolute URL');
+    }
+    if (parsed.protocol !== 'https:') {
+        throw new errors_1.BadInputError('Webhook URL must use HTTPS');
+    }
+    return { url };
+}
+function verifyWebhook(rawBody, timestamp, signature, secret, toleranceSeconds = exports.WEBHOOK_TOLERANCE_SECONDS) {
+    if (!secret || typeof secret !== 'string') {
+        throw new errors_1.BadInputError('Webhook signing secret must be a non-empty string');
+    }
+    const stamp = Array.isArray(timestamp) ? timestamp[0] : timestamp;
+    const header = Array.isArray(signature) ? signature.join(',') : signature;
+    if (!stamp || !header || !/^\d+$/.test(stamp.trim())) {
+        return false;
+    }
+    if (Math.abs(Date.now() / 1000 - Number(stamp.trim())) > toleranceSeconds) {
+        return false;
+    }
+    const body = typeof rawBody === 'string' ? Buffer.from(rawBody, 'utf8') : rawBody;
+    const expected = Buffer.from(`${exports.WEBHOOK_SIGNATURE_VERSION}=` +
+        (0, crypto_1.createHmac)('sha256', secret)
+            .update(Buffer.concat([Buffer.from(`${stamp.trim()}.`, 'utf8'), body]))
+            .digest('hex'), 'utf8');
+    return header.split(',').some((entry) => {
+        const actual = Buffer.from(entry.trim(), 'utf8');
+        return actual.length === expected.length && (0, crypto_1.timingSafeEqual)(actual, expected);
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './v2';

package/dist/index.js

@@ -0,0 +1,17 @@
+"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 });
+__exportStar(require("./v2"), exports);

package/dist/types.d.ts

@@ -0,0 +1,55 @@
+export declare enum JobStatus {
+    QUEUED = "queued",
+    IN_PROGRESS = "in_progress",
+    COMPLETED = "completed",
+    FAILED = "failed",
+    NSFW = "nsfw",
+    CANCELED = "canceled"
+}
+export interface Artifact {
+    id: string;
+    type: 'image' | 'video' | 'audio' | (string & {});
+    url: string;
+    content_type?: string | null;
+    public_artifact_id?: string | null;
+    visibility?: string;
+    size_bytes?: number | null;
+    width?: number | null;
+    height?: number | null;
+    duration_ms?: number | null;
+    checksum_sha256?: string | null;
+}
+export interface JobError {
+    code: string;
+    message: string;
+    category?: string;
+    stage?: string;
+    retryable?: boolean;
+    retry_after_seconds?: number | null;
+    public_reason?: string;
+    next_action?: string;
+    details?: Record<string, unknown>;
+}
+export interface WebhookPayload {
+    url: string;
+}
+export interface UploadResponse {
+    public_url: string;
+    upload_url: string;
+    upload_method: string;
+    upload_headers: Record<string, string>;
+    content_type: string;
+    expires_at: string;
+    asset_id: string;
+}
+export type WebhookEventType = 'job.completed' | 'job.failed' | 'job.canceled';
+export interface WebhookEvent {
+    event: WebhookEventType;
+    request_id: string;
+    job_id: string;
+    status: 'OK' | 'ERROR';
+    payload?: {
+        artifacts: Artifact[];
+    };
+    error?: JobError;
+}

package/dist/types.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobStatus = void 0;
+var JobStatus;
+(function (JobStatus) {
+    JobStatus["QUEUED"] = "queued";
+    JobStatus["IN_PROGRESS"] = "in_progress";
+    JobStatus["COMPLETED"] = "completed";
+    JobStatus["FAILED"] = "failed";
+    JobStatus["NSFW"] = "nsfw";
+    JobStatus["CANCELED"] = "canceled";
+})(JobStatus || (exports.JobStatus = JobStatus = {}));

package/dist/utils/retry.d.ts

@@ -0,0 +1,11 @@
+export interface RetryConfig {
+    maxRetries: number;
+    backoff: number;
+    maxBackoff: number;
+}
+export declare const sleep: (ms: number) => Promise<void>;
+export declare function parseRetryAfter(value: unknown): number | undefined;
+export declare function isRetryableError(error: unknown): boolean;
+export declare function retryAfterMs(error: unknown): number | undefined;
+export declare function backoffDelay(attempt: number, config: RetryConfig, error?: unknown): number;
+export declare function retryWithBackoff<T>(fn: () => Promise<T>, config: RetryConfig): Promise<T>;

package/dist/utils/retry.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sleep = void 0;
+exports.parseRetryAfter = parseRetryAfter;
+exports.isRetryableError = isRetryableError;
+exports.retryAfterMs = retryAfterMs;
+exports.backoffDelay = backoffDelay;
+exports.retryWithBackoff = retryWithBackoff;
+const axios_1 = __importDefault(require("axios"));
+const errors_1 = require("../errors");
+const RETRYABLE_NETWORK_CODES = new Set([
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'ENOTFOUND',
+    'ECONNABORTED',
+    'ECONNREFUSED',
+    'EAI_AGAIN',
+    'EPIPE',
+    'ERR_NETWORK',
+]);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+exports.sleep = sleep;
+function parseRetryAfter(value) {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) && value >= 0 ? value : undefined;
+    }
+    if (typeof value !== 'string' || value.trim() === '') {
+        return undefined;
+    }
+    const seconds = Number(value);
+    if (Number.isFinite(seconds)) {
+        return seconds >= 0 ? seconds : undefined;
+    }
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, (date - Date.now()) / 1000) : undefined;
+}
+function isRetryableError(error) {
+    if (error instanceof errors_1.APIError) {
+        if (error.statusCode === undefined) {
+            return RETRYABLE_NETWORK_CODES.has(error.code ?? '');
+        }
+        return error.statusCode === 429 || error.statusCode >= 500;
+    }
+    if (axios_1.default.isAxiosError(error)) {
+        if (error.response) {
+            return error.response.status === 429 || error.response.status >= 500;
+        }
+        return RETRYABLE_NETWORK_CODES.has(error.code ?? '');
+    }
+    return false;
+}
+function retryAfterMs(error) {
+    if (error instanceof errors_1.APIError) {
+        return error.retryAfter === undefined ? undefined : error.retryAfter * 1000;
+    }
+    if (axios_1.default.isAxiosError(error)) {
+        const seconds = parseRetryAfter(error.response?.headers?.['retry-after']);
+        return seconds === undefined ? undefined : seconds * 1000;
+    }
+    return undefined;
+}
+function backoffDelay(attempt, config, error) {
+    const hinted = retryAfterMs(error);
+    if (hinted !== undefined) {
+        return Math.min(hinted, config.maxBackoff);
+    }
+    return Math.min(config.backoff * Math.pow(2, attempt) + Math.random() * 1000, config.maxBackoff);
+}
+async function retryWithBackoff(fn, config) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            if (attempt >= config.maxRetries || !isRetryableError(error)) {
+                throw error;
+            }
+            await (0, exports.sleep)(backoffDelay(attempt, config, error));
+        }
+    }
+}

package/dist/v2/client.d.ts

@@ -0,0 +1,24 @@
+import { ClientConfig } from '../config';
+import { EndpointInputMap, V2Response } from './types';
+export interface V2ClientConfig extends ClientConfig {
+    credentials?: string;
+    apiKey?: string;
+}
+export interface SubscribeOptions<TInput = Record<string, unknown>> {
+    input: TInput;
+    webhook?: {
+        url: string;
+    };
+    withPolling?: boolean;
+    idempotencyKey?: string;
+}
+export type SubscribeInput<TEndpoint extends string> = TEndpoint extends keyof EndpointInputMap ? EndpointInputMap[TEndpoint] : Record<string, unknown>;
+export interface SumeClient {
+    subscribe<TEndpoint extends string>(endpoint: TEndpoint, options: SubscribeOptions<SubscribeInput<TEndpoint>>): Promise<V2Response>;
+    upload(data: Buffer | Uint8Array, contentType: string): Promise<string>;
+    uploadImage(imageBuffer: Buffer | Uint8Array, format?: 'jpeg' | 'png' | 'webp'): Promise<string>;
+    configure(config: V2ClientConfig): void;
+}
+export declare function createSumeClient(config?: V2ClientConfig): SumeClient;
+export declare function configure(config: V2ClientConfig): void;
+export declare function reset(): void;