@viewrium/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,350 @@
+/**
+ * Typed error hierarchy for the Viewrium SDK.
+ *
+ * All API-originated failures inherit from `ViewriumError`. Network-level
+ * failures (connection reset, DNS) bubble up as the underlying fetch error
+ * unchanged.
+ */
+declare class ViewriumError extends Error {
+    readonly statusCode: number | undefined;
+    readonly responseBody: unknown;
+    constructor(message: string, options?: {
+        statusCode?: number;
+        responseBody?: unknown;
+    });
+}
+declare class AuthError extends ViewriumError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        responseBody?: unknown;
+    });
+}
+declare class NotFoundError extends ViewriumError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        responseBody?: unknown;
+    });
+}
+declare class ValidationError extends ViewriumError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        responseBody?: unknown;
+    });
+}
+declare class RateLimitError extends ViewriumError {
+    readonly retryAfter: number | undefined;
+    constructor(message: string, options?: {
+        statusCode?: number;
+        responseBody?: unknown;
+        retryAfter?: number;
+    });
+}
+declare class APIError extends ViewriumError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        responseBody?: unknown;
+    });
+}
+
+/**
+ * Public types for the Viewrium SDK.
+ *
+ * Response shapes mirror the backend JSON contract (snake_case). Request
+ * param interfaces use camelCase; the SDK maps camelCase → snake_case on
+ * the wire.
+ */
+interface ViewriumOptions {
+    /** Override the API key. Defaults to the value passed to `new Viewrium(...)`. */
+    apiKey?: string;
+    /** Base URL. Defaults to `process.env.VIEWRIUM_API_BASE` or `https://api.viewrium.com`. */
+    apiBase?: string;
+    /** Per-request timeout in milliseconds. Default 60_000. */
+    timeoutMs?: number;
+    /** Retries on 429 / 5xx. Default 3. */
+    maxRetries?: number;
+    /** Override `globalThis.fetch` (test seams / custom transports). */
+    fetch?: typeof fetch;
+}
+type SizeUnit = "cm" | "in";
+type ModelStatus = "uploading" | "processing" | "queueing" | "successful" | "failed" | "expired";
+type SourceType = "scan" | "upload" | "image";
+type UsageEventType = "generation.created" | "generation.completed" | "generation.failed" | "view" | "ar_enter" | "ar_session_ended";
+interface Model {
+    id: string;
+    project_id: string | null;
+    custom_id: string | null;
+    title: string | null;
+    description: string | null;
+    price: number | null;
+    currency: string | null;
+    status: ModelStatus;
+    source_type: SourceType | null;
+    model_url: string | null;
+    thumbnail_url: string | null;
+    height: number | null;
+    width: number | null;
+    depth: number | null;
+    scale_factor: number | null;
+    tags: string[];
+    metadata: Record<string, unknown>;
+    display_enabled: boolean;
+    created_at: string;
+    completed_at: string | null;
+    [key: string]: unknown;
+}
+interface ModelListResponse {
+    data: Model[];
+    limit: number;
+    offset: number;
+}
+interface ModelEvent {
+    id: string;
+    event_type: UsageEventType;
+    timestamp: string;
+    metadata: Record<string, unknown>;
+}
+interface ModelEventListResponse {
+    data: ModelEvent[];
+    limit: number;
+    offset: number;
+}
+interface DeletedResponse {
+    id: string;
+    deleted: true;
+}
+interface ApiKey {
+    id: string;
+    name: string | null;
+    key_type: "secret" | "publishable";
+    key_prefix: string;
+    last_used_at: string | null;
+    revoked_at: string | null;
+    created_at: string;
+}
+/** Returned by `apiKeys.create` - `key` is plaintext, shown once. */
+interface ApiKeyWithSecret extends Omit<ApiKey, "last_used_at" | "revoked_at"> {
+    key: string;
+}
+interface ApiKeyListResponse {
+    data: ApiKey[];
+}
+interface RevokedResponse {
+    id: string;
+    revoked: true;
+}
+interface UsageSummary {
+    org_id: string;
+    plan_tier: "free" | "pro" | "enterprise";
+    since: string | null;
+    until: string | null;
+    counts: Partial<Record<UsageEventType, number>>;
+}
+interface TagSummary {
+    tag: string;
+    count: number;
+}
+interface TagListResponse {
+    data: TagSummary[];
+}
+interface ModelCreateParams {
+    customId?: string;
+    title?: string;
+    description?: string;
+    /** Provide one of `images` (URL list) or `sourceUrl` - not both. */
+    images?: string[];
+    /** Product page URL. Server extracts candidate images. */
+    sourceUrl?: string;
+    height?: number;
+    sizeUnit?: SizeUnit;
+    tags?: string[];
+    price?: number;
+    currency?: string;
+    metadata?: Record<string, unknown>;
+    displayEnabled?: boolean;
+}
+interface ModelCreateFromImagesParams {
+    title?: string;
+    customId?: string;
+    description?: string;
+    height?: number;
+    sizeUnit?: SizeUnit;
+    tags?: string[];
+    displayEnabled?: boolean;
+}
+interface ModelCreateFromVideoParams extends ModelCreateFromImagesParams {
+}
+interface ModelUpdateParams {
+    customId?: string;
+    title?: string;
+    description?: string;
+    price?: number;
+    currency?: string;
+    height?: number;
+    sizeUnit?: SizeUnit;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    displayEnabled?: boolean;
+}
+interface ModelListParams {
+    tag?: string;
+    tags?: string[] | string;
+    customId?: string;
+    status?: ModelStatus;
+    limit?: number;
+    offset?: number;
+}
+interface ModelListEventsParams {
+    limit?: number;
+    offset?: number;
+}
+interface ApiKeyCreateParams {
+    name?: string;
+    /**
+     * Type of key to create. Defaults to `"secret"`.
+     * - `"secret"` (sk_*): server-only, authenticates /v1/* calls.
+     * - `"publishable"` (pk_*): client-safe, used by the embed tag. Origin
+     *   restrictions inherit from the project's allowed_domains.
+     */
+    keyType?: "secret" | "publishable";
+}
+interface UsageRetrieveParams {
+    /** ISO 8601 lower bound (inclusive). */
+    since?: string;
+    /** ISO 8601 upper bound (inclusive). */
+    until?: string;
+}
+/**
+ * A file passed to multipart endpoints.
+ *
+ * - In Node: a path string (SDK reads it via `fs.readFile`) or a `Blob`/`File`.
+ * - In browsers / edge runtimes: `Blob` / `File` (native).
+ * - Anywhere: a `{ data, filename, contentType? }` record with raw bytes.
+ */
+type FileInput = string | Blob | {
+    data: Uint8Array | ArrayBuffer | Blob;
+    filename?: string;
+    contentType?: string;
+};
+
+/**
+ * Models resource - 3D models (backed by the `scans` table).
+ *
+ * Mirrors the 8 `/v1/models*` endpoints. camelCase param names are mapped
+ * to the snake_case wire contract on the way out; response shapes pass
+ * through as-is.
+ */
+
+declare class ModelsResource {
+    private readonly client;
+    constructor(client: Viewrium);
+    create(params: ModelCreateParams): Promise<Model>;
+    createFromImages(images: FileInput[], params?: ModelCreateFromImagesParams): Promise<Model>;
+    createFromVideo(video: FileInput, params?: ModelCreateFromVideoParams): Promise<Model>;
+    retrieve(modelId: string): Promise<Model>;
+    list(params?: ModelListParams): Promise<ModelListResponse>;
+    modify(modelId: string, params: ModelUpdateParams): Promise<Model>;
+    delete(modelId: string): Promise<DeletedResponse>;
+    listEvents(modelId: string, params?: ModelListEventsParams): Promise<ModelEventListResponse>;
+}
+
+/**
+ * Api keys resource.
+ *
+ * Creates secret (`sk_*`) or publishable (`pk_*`) keys. pk keys inherit
+ * origin restrictions from their project's `allowed_domains`. The plaintext
+ * key is returned ONCE from `create()`; store it securely on your side.
+ */
+
+declare class ApiKeysResource {
+    private readonly client;
+    constructor(client: Viewrium);
+    create(params?: ApiKeyCreateParams): Promise<ApiKeyWithSecret>;
+    list(): Promise<ApiKeyListResponse>;
+    delete(keyId: string): Promise<RevokedResponse>;
+}
+
+/**
+ * Usage resource.
+ *
+ * Returns aggregated event counts for the caller's organization. Internal
+ * service events (rodin / gemini / scrape / convert / store) are never
+ * exposed here.
+ */
+
+declare class UsageResource {
+    private readonly client;
+    constructor(client: Viewrium);
+    retrieve(params?: UsageRetrieveParams): Promise<UsageSummary>;
+}
+
+/**
+ * Tags resource.
+ *
+ * Lists unique tags across the caller's organization with per-tag model
+ * counts. Tags are created implicitly when assigned to a model; there is
+ * no POST /v1/tags endpoint.
+ */
+
+declare class TagsResource {
+    private readonly client;
+    constructor(client: Viewrium);
+    list(): Promise<TagListResponse>;
+}
+
+/**
+ * Viewrium client.
+ *
+ * Instantiate once per api key:
+ *
+ *     const viewrium = new Viewrium(process.env.VIEWRIUM_API_KEY!);
+ *     const model = await viewrium.models.create({ images: [...] });
+ *
+ * The client uses `globalThis.fetch` by default (Node 18+, browsers, edge
+ * runtimes all provide it). Pass `fetch` in options for custom transports
+ * or testing.
+ */
+
+interface RequestOptions {
+    method: string;
+    path: string;
+    query?: Record<string, unknown>;
+    json?: unknown;
+    body?: BodyInit;
+    headers?: Record<string, string>;
+    /** Override per-request timeout in ms. */
+    timeoutMs?: number;
+}
+declare class Viewrium {
+    readonly models: ModelsResource;
+    readonly apiKeys: ApiKeysResource;
+    readonly usage: UsageResource;
+    readonly tags: TagsResource;
+    private readonly apiKey;
+    private readonly apiBase;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(apiKey?: string, options?: ViewriumOptions);
+    /** Low-level request. Resources delegate here. */
+    request<T = unknown>(options: RequestOptions): Promise<T>;
+    private buildUrl;
+    private buildHeaders;
+    private buildBody;
+}
+
+/**
+ * Official JavaScript / TypeScript SDK for the Viewrium API.
+ *
+ *     import Viewrium from "@viewrium/sdk";
+ *
+ *     const viewrium = new Viewrium(process.env.VIEWRIUM_API_KEY!);
+ *
+ *     const model = await viewrium.models.create({
+ *       customId: "sku-1",
+ *       images: ["https://example.com/img1.jpg"],
+ *       height: 90,
+ *       tags: ["chair", "summer-2026"],
+ *     });
+ */
+
+export { APIError, type ApiKey, type ApiKeyCreateParams, type ApiKeyListResponse, type ApiKeyWithSecret, ApiKeysResource, AuthError, type DeletedResponse, type FileInput, type Model, type ModelCreateFromImagesParams, type ModelCreateFromVideoParams, type ModelCreateParams, type ModelEvent, type ModelEventListResponse, type ModelListEventsParams, type ModelListParams, type ModelListResponse, type ModelStatus, type ModelUpdateParams, ModelsResource, NotFoundError, RateLimitError, type RequestOptions, type RevokedResponse, type SizeUnit, type SourceType, type TagListResponse, type TagSummary, TagsResource, type UsageEventType, UsageResource, type UsageRetrieveParams, type UsageSummary, ValidationError, Viewrium, ViewriumError, type ViewriumOptions, Viewrium as default };

package/dist/index.d.ts

@@ -0,0 +1,350 @@
+/**
+ * Typed error hierarchy for the Viewrium SDK.
+ *
+ * All API-originated failures inherit from `ViewriumError`. Network-level
+ * failures (connection reset, DNS) bubble up as the underlying fetch error
+ * unchanged.
+ */
+declare class ViewriumError extends Error {
+    readonly statusCode: number | undefined;
+    readonly responseBody: unknown;
+    constructor(message: string, options?: {
+        statusCode?: number;
+        responseBody?: unknown;
+    });
+}
+declare class AuthError extends ViewriumError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        responseBody?: unknown;
+    });
+}
+declare class NotFoundError extends ViewriumError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        responseBody?: unknown;
+    });
+}
+declare class ValidationError extends ViewriumError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        responseBody?: unknown;
+    });
+}
+declare class RateLimitError extends ViewriumError {
+    readonly retryAfter: number | undefined;
+    constructor(message: string, options?: {
+        statusCode?: number;
+        responseBody?: unknown;
+        retryAfter?: number;
+    });
+}
+declare class APIError extends ViewriumError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        responseBody?: unknown;
+    });
+}
+
+/**
+ * Public types for the Viewrium SDK.
+ *
+ * Response shapes mirror the backend JSON contract (snake_case). Request
+ * param interfaces use camelCase; the SDK maps camelCase → snake_case on
+ * the wire.
+ */
+interface ViewriumOptions {
+    /** Override the API key. Defaults to the value passed to `new Viewrium(...)`. */
+    apiKey?: string;
+    /** Base URL. Defaults to `process.env.VIEWRIUM_API_BASE` or `https://api.viewrium.com`. */
+    apiBase?: string;
+    /** Per-request timeout in milliseconds. Default 60_000. */
+    timeoutMs?: number;
+    /** Retries on 429 / 5xx. Default 3. */
+    maxRetries?: number;
+    /** Override `globalThis.fetch` (test seams / custom transports). */
+    fetch?: typeof fetch;
+}
+type SizeUnit = "cm" | "in";
+type ModelStatus = "uploading" | "processing" | "queueing" | "successful" | "failed" | "expired";
+type SourceType = "scan" | "upload" | "image";
+type UsageEventType = "generation.created" | "generation.completed" | "generation.failed" | "view" | "ar_enter" | "ar_session_ended";
+interface Model {
+    id: string;
+    project_id: string | null;
+    custom_id: string | null;
+    title: string | null;
+    description: string | null;
+    price: number | null;
+    currency: string | null;
+    status: ModelStatus;
+    source_type: SourceType | null;
+    model_url: string | null;
+    thumbnail_url: string | null;
+    height: number | null;
+    width: number | null;
+    depth: number | null;
+    scale_factor: number | null;
+    tags: string[];
+    metadata: Record<string, unknown>;
+    display_enabled: boolean;
+    created_at: string;
+    completed_at: string | null;
+    [key: string]: unknown;
+}
+interface ModelListResponse {
+    data: Model[];
+    limit: number;
+    offset: number;
+}
+interface ModelEvent {
+    id: string;
+    event_type: UsageEventType;
+    timestamp: string;
+    metadata: Record<string, unknown>;
+}
+interface ModelEventListResponse {
+    data: ModelEvent[];
+    limit: number;
+    offset: number;
+}
+interface DeletedResponse {
+    id: string;
+    deleted: true;
+}
+interface ApiKey {
+    id: string;
+    name: string | null;
+    key_type: "secret" | "publishable";
+    key_prefix: string;
+    last_used_at: string | null;
+    revoked_at: string | null;
+    created_at: string;
+}
+/** Returned by `apiKeys.create` - `key` is plaintext, shown once. */
+interface ApiKeyWithSecret extends Omit<ApiKey, "last_used_at" | "revoked_at"> {
+    key: string;
+}
+interface ApiKeyListResponse {
+    data: ApiKey[];
+}
+interface RevokedResponse {
+    id: string;
+    revoked: true;
+}
+interface UsageSummary {
+    org_id: string;
+    plan_tier: "free" | "pro" | "enterprise";
+    since: string | null;
+    until: string | null;
+    counts: Partial<Record<UsageEventType, number>>;
+}
+interface TagSummary {
+    tag: string;
+    count: number;
+}
+interface TagListResponse {
+    data: TagSummary[];
+}
+interface ModelCreateParams {
+    customId?: string;
+    title?: string;
+    description?: string;
+    /** Provide one of `images` (URL list) or `sourceUrl` - not both. */
+    images?: string[];
+    /** Product page URL. Server extracts candidate images. */
+    sourceUrl?: string;
+    height?: number;
+    sizeUnit?: SizeUnit;
+    tags?: string[];
+    price?: number;
+    currency?: string;
+    metadata?: Record<string, unknown>;
+    displayEnabled?: boolean;
+}
+interface ModelCreateFromImagesParams {
+    title?: string;
+    customId?: string;
+    description?: string;
+    height?: number;
+    sizeUnit?: SizeUnit;
+    tags?: string[];
+    displayEnabled?: boolean;
+}
+interface ModelCreateFromVideoParams extends ModelCreateFromImagesParams {
+}
+interface ModelUpdateParams {
+    customId?: string;
+    title?: string;
+    description?: string;
+    price?: number;
+    currency?: string;
+    height?: number;
+    sizeUnit?: SizeUnit;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    displayEnabled?: boolean;
+}
+interface ModelListParams {
+    tag?: string;
+    tags?: string[] | string;
+    customId?: string;
+    status?: ModelStatus;
+    limit?: number;
+    offset?: number;
+}
+interface ModelListEventsParams {
+    limit?: number;
+    offset?: number;
+}
+interface ApiKeyCreateParams {
+    name?: string;
+    /**
+     * Type of key to create. Defaults to `"secret"`.
+     * - `"secret"` (sk_*): server-only, authenticates /v1/* calls.
+     * - `"publishable"` (pk_*): client-safe, used by the embed tag. Origin
+     *   restrictions inherit from the project's allowed_domains.
+     */
+    keyType?: "secret" | "publishable";
+}
+interface UsageRetrieveParams {
+    /** ISO 8601 lower bound (inclusive). */
+    since?: string;
+    /** ISO 8601 upper bound (inclusive). */
+    until?: string;
+}
+/**
+ * A file passed to multipart endpoints.
+ *
+ * - In Node: a path string (SDK reads it via `fs.readFile`) or a `Blob`/`File`.
+ * - In browsers / edge runtimes: `Blob` / `File` (native).
+ * - Anywhere: a `{ data, filename, contentType? }` record with raw bytes.
+ */
+type FileInput = string | Blob | {
+    data: Uint8Array | ArrayBuffer | Blob;
+    filename?: string;
+    contentType?: string;
+};
+
+/**
+ * Models resource - 3D models (backed by the `scans` table).
+ *
+ * Mirrors the 8 `/v1/models*` endpoints. camelCase param names are mapped
+ * to the snake_case wire contract on the way out; response shapes pass
+ * through as-is.
+ */
+
+declare class ModelsResource {
+    private readonly client;
+    constructor(client: Viewrium);
+    create(params: ModelCreateParams): Promise<Model>;
+    createFromImages(images: FileInput[], params?: ModelCreateFromImagesParams): Promise<Model>;
+    createFromVideo(video: FileInput, params?: ModelCreateFromVideoParams): Promise<Model>;
+    retrieve(modelId: string): Promise<Model>;
+    list(params?: ModelListParams): Promise<ModelListResponse>;
+    modify(modelId: string, params: ModelUpdateParams): Promise<Model>;
+    delete(modelId: string): Promise<DeletedResponse>;
+    listEvents(modelId: string, params?: ModelListEventsParams): Promise<ModelEventListResponse>;
+}
+
+/**
+ * Api keys resource.
+ *
+ * Creates secret (`sk_*`) or publishable (`pk_*`) keys. pk keys inherit
+ * origin restrictions from their project's `allowed_domains`. The plaintext
+ * key is returned ONCE from `create()`; store it securely on your side.
+ */
+
+declare class ApiKeysResource {
+    private readonly client;
+    constructor(client: Viewrium);
+    create(params?: ApiKeyCreateParams): Promise<ApiKeyWithSecret>;
+    list(): Promise<ApiKeyListResponse>;
+    delete(keyId: string): Promise<RevokedResponse>;
+}
+
+/**
+ * Usage resource.
+ *
+ * Returns aggregated event counts for the caller's organization. Internal
+ * service events (rodin / gemini / scrape / convert / store) are never
+ * exposed here.
+ */
+
+declare class UsageResource {
+    private readonly client;
+    constructor(client: Viewrium);
+    retrieve(params?: UsageRetrieveParams): Promise<UsageSummary>;
+}
+
+/**
+ * Tags resource.
+ *
+ * Lists unique tags across the caller's organization with per-tag model
+ * counts. Tags are created implicitly when assigned to a model; there is
+ * no POST /v1/tags endpoint.
+ */
+
+declare class TagsResource {
+    private readonly client;
+    constructor(client: Viewrium);
+    list(): Promise<TagListResponse>;
+}
+
+/**
+ * Viewrium client.
+ *
+ * Instantiate once per api key:
+ *
+ *     const viewrium = new Viewrium(process.env.VIEWRIUM_API_KEY!);
+ *     const model = await viewrium.models.create({ images: [...] });
+ *
+ * The client uses `globalThis.fetch` by default (Node 18+, browsers, edge
+ * runtimes all provide it). Pass `fetch` in options for custom transports
+ * or testing.
+ */
+
+interface RequestOptions {
+    method: string;
+    path: string;
+    query?: Record<string, unknown>;
+    json?: unknown;
+    body?: BodyInit;
+    headers?: Record<string, string>;
+    /** Override per-request timeout in ms. */
+    timeoutMs?: number;
+}
+declare class Viewrium {
+    readonly models: ModelsResource;
+    readonly apiKeys: ApiKeysResource;
+    readonly usage: UsageResource;
+    readonly tags: TagsResource;
+    private readonly apiKey;
+    private readonly apiBase;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(apiKey?: string, options?: ViewriumOptions);
+    /** Low-level request. Resources delegate here. */
+    request<T = unknown>(options: RequestOptions): Promise<T>;
+    private buildUrl;
+    private buildHeaders;
+    private buildBody;
+}
+
+/**
+ * Official JavaScript / TypeScript SDK for the Viewrium API.
+ *
+ *     import Viewrium from "@viewrium/sdk";
+ *
+ *     const viewrium = new Viewrium(process.env.VIEWRIUM_API_KEY!);
+ *
+ *     const model = await viewrium.models.create({
+ *       customId: "sku-1",
+ *       images: ["https://example.com/img1.jpg"],
+ *       height: 90,
+ *       tags: ["chair", "summer-2026"],
+ *     });
+ */
+
+export { APIError, type ApiKey, type ApiKeyCreateParams, type ApiKeyListResponse, type ApiKeyWithSecret, ApiKeysResource, AuthError, type DeletedResponse, type FileInput, type Model, type ModelCreateFromImagesParams, type ModelCreateFromVideoParams, type ModelCreateParams, type ModelEvent, type ModelEventListResponse, type ModelListEventsParams, type ModelListParams, type ModelListResponse, type ModelStatus, type ModelUpdateParams, ModelsResource, NotFoundError, RateLimitError, type RequestOptions, type RevokedResponse, type SizeUnit, type SourceType, type TagListResponse, type TagSummary, TagsResource, type UsageEventType, UsageResource, type UsageRetrieveParams, type UsageSummary, ValidationError, Viewrium, ViewriumError, type ViewriumOptions, Viewrium as default };