@stackshift-cloud/sdk 1.0.0 → 1.2.0

package/README.md

@@ -2,6 +2,26 @@
 
 Official JavaScript and TypeScript SDK for StackShift.
 
+## Governed media and galleries
+
+Use a separate server-side client for each Assets space; the namespace is fixed on that client. Project membership does not grant Assets access.
+
+```ts
+const studio = new StackShift({
+  apiKey: process.env.STACKSHIFT_API_KEY,
+  assetSpaceId: 'your-asset-space-uuid',
+})
+const page = await studio.assets.dam.publications({ status: 'published' })
+if (page.next_cursor) {
+  const next = await studio.assets.dam.publications({ status: 'published', cursor: page.next_cursor })
+}
+const gallery = await studio.assets.dam.resolveGallery('published-gallery-uuid')
+```
+
+`assets.dam` also exposes collaborators, typed metadata schemas, bucket governance, publication transitions, model processing, gallery drafts and picker capabilities. Updates use explicit revisions. Submission needs `assets:write`, review needs `assets:admin`, and publication/withdrawal needs `assets:publish`, in addition to the corresponding Assets grant.
+
+Keep account credentials on your server. Give `@stackshift-cloud/assets-picker` a short-lived, origin-restricted capability; give `@stackshift-cloud/assets-gallery` a server resolver for approved media. Store publication/gallery IDs and versions, never delivery URLs. Model processing is an explicitly enabled pilot and requires the qualified isolated worker described in `packages/assets-model-processor/README.md`.
+
 ## Install
 
 ```bash
@@ -218,6 +238,66 @@ export class AssetsService {
 }
 ```
 
+## Storage connections and migrations
+
+Use AWS AssumeRole for S3 whenever possible. The returned `external_id` belongs in the role trust policy; credentials are write-only and are never returned by Stackshift.
+
+```ts
+const connection = await stackshift.assets.connections.create({
+  provider: 'aws_s3',
+  name: 'Production media',
+  configuration: {
+    bucket: 'acme-media',
+    region: 'us-east-1',
+    role_arn: 'arn:aws:iam::123456789012:role/StackshiftAssets',
+    auth_type: 'assume_role',
+  },
+})
+
+await stackshift.assets.connections.verify(connection.id)
+
+const dryRun = await stackshift.assets.migrations.start({
+  source_connection_id: connection.id,
+  destination_bucket_id: 'assets_bucket_id',
+  source_prefix: 'legacy',
+  conflict_policy: 'skip',
+  dry_run: true,
+})
+
+const report = await stackshift.assets.migrations.downloadReport(dryRun.id, 'csv')
+```
+
+Native Stackshift S2 storage uses a bucket reference and internal authorization, never copied S2 access keys:
+
+```ts
+const s2 = await stackshift.assets.storage.createS2Bucket({ name: 'asset-originals', region: 'us-east-1' })
+await stackshift.assets.storage.configure('assets_bucket_id', 3, {
+  storage_mode: 'stackshift_s2',
+  s2_bucket_id: s2.id,
+  object_prefix: 'originals',
+  derivative_prefix: 'derived',
+  auto_extract_text: true,
+})
+```
+
+## OCR and browser upload capabilities
+
+```ts
+const extraction = await stackshift.assets.text.start('asset_id', { language: 'eng' })
+const current = await stackshift.assets.text.get('asset_id')
+
+const capability = await stackshift.assets.uploadCapabilities.create({
+  bucket: 'uploads',
+  key_prefix: 'customers/user_123',
+  allowed_mime_types: ['image/png', 'image/jpeg'],
+  allowed_origins: ['https://app.example.com'],
+  max_bytes: 25 * 1024 * 1024,
+  expires_in: '15m',
+})
+```
+
+Create capabilities only in trusted backend code. Send `capability.token` to `@stackshift-cloud/assets-widget`; never put the Stackshift API key in a browser bundle.
+
 For larger uploads, create a signed upload URL on your NestJS server and let the browser upload directly.
 
 ## Direct browser uploads
@@ -247,3 +327,40 @@ await fetch(upload.url, {
 This is the recommended pattern for React, Next.js, TanStack Start, and any browser app. The browser never receives your StackShift API key.
 
 StackShift chooses storage nodes, writes to StackShift-owned disks, replicates internally, and returns CDN-ready asset URLs. SDK users never choose storage nodes and never receive disk paths.
+
+### Campaign drafts and engagement
+
+Create campaigns with `content: { subject, html, text, editorMode: 'code' }`, or keep using a template/version. `mail.campaigns.update(id, { ...draft, revision })` saves a full draft; `preview`, `test`, `send(id, revision)`, and `schedule(id, sendAt, revision)` support review and dispatch. A stale revision returns 409.
+
+Mail send inputs accept `tracking: { opens: false, clicks: true }`. Each omitted setting inherits the workspace default. Use `mail.tracking.settings()` / `updateSettings()`, `message(id)` / `campaign(id)` for reports, and `domains()` / `createDomain()` / `verifyDomain()` / `updateDomain()` for branded hosts. Features must be enabled on the deployment. Opens are approximate; suspected automation is reported separately. Detailed activity expires after 90 days. Tests and OTPs never track.
+
+### Isolated testing, brands, migration, and spending
+
+Use a `sspat_test_` credential with `simulation: { scenario: 'delayed' }` for a 60-second simulated delay. Other outcomes are delivered, bounced, and complained. Test resources are isolated; no real email is delivered.
+
+```ts
+const brand = await client.mail.brands.create({ name: 'Product', editableFields: ['company'] })
+const audience = await client.mail.audiences.create({ brandId: brand.id, name: 'Product news' })
+```
+
+Every audience requires an explicit brand. Contact names/attributes are shared within that brand while consent stays per audience. `mail.automations`, `mail.forms`, and `mail.segments` expose audience-owned resources.
+
+`mail.migration` supports public DNS audits/plans and authenticated checklists. `mail.billing.summary()` and `mail.campaigns.estimate(id)` expose allowance, credit, and blocking reasons. Pass approved maximum kobo as the third argument to `send(id, revision, approvedMaxKobo)` or the fourth to `schedule(id, sendAt, revision, approvedMaxKobo)`. Zero is a valid hard maximum. Billing is inactive until a rate card is explicitly published and activated; funding and prepaid opt-in are separate owner-only dashboard actions.
+
+## Native video, governed DAM and product rendering
+
+Use the space-scoped DAM and video clients for collaborators, metadata schemas, bucket governance, reviewed publications, picker capabilities, model preparation, product rendering, galleries, version-pinned encoding, captions and playback sessions.
+
+```ts
+const dam = sdk.assets.dam
+const video = sdk.assets.video
+const schema = await dam.createMetadataSchema({ name: 'Products', fields: [{
+  key: 'product_name', label: 'Product name', type: 'text', required: true,
+}] })
+const published = await dam.publishMetadataSchema(schema.id, schema.revision)
+const workspace = await video.workspace(assetId)
+```
+
+Mutations carry the supplied revision in `If-Match`. Model preparation and rendering carry an idempotency key; render submission also carries the accepted maximum units. Playback renewal and events authenticate with the session credential, not the account key. Keep these clients on your backend and return grants with `Cache-Control: private, no-store`.
+
+See the [Assets SDK guide](https://docs.stackshift.cloud/assets/sdk-media-workflows) and its linked feature guides for complete language examples, inputs, permissions, review transitions and browser callbacks.

package/dist/asset-media-v2.d.ts

@@ -0,0 +1,65 @@
+export type AssetMediaKind = 'image' | 'video';
+export type AssetTransformOutputKind = 'image' | 'video' | 'audio' | 'thumbnail';
+export type AssetAnimationPolicy = 'first' | 'preserve' | 'reject';
+export interface AssetTransformOperation {
+    type: 'crop' | 'resize' | 'rotate' | 'blur' | 'radius' | 'dpr' | 'background' | 'overlay' | 'trim' | 'fps' | 'timestamp';
+    mode?: 'explicit' | 'fit' | 'fill' | 'pad';
+    gravity?: 'northwest' | 'north' | 'northeast' | 'west' | 'centre' | 'east' | 'southwest' | 'south' | 'southeast';
+    width?: number;
+    height?: number;
+    x?: number;
+    y?: number;
+    degrees?: number;
+    sigma?: number;
+    radius?: number;
+    dpr?: number;
+    color?: string;
+    asset_id?: string;
+    opacity?: number;
+    start_seconds?: number;
+    end_seconds?: number;
+    fps?: number;
+    timestamp_seconds?: number;
+}
+export interface AssetTransformDefinition {
+    version: 2;
+    media_kind: AssetMediaKind;
+    animation?: AssetAnimationPolicy;
+    operations: AssetTransformOperation[];
+    output: {
+        kind: AssetTransformOutputKind;
+        format: 'jpeg' | 'png' | 'webp' | 'avif' | 'mp4' | 'mp3' | 'aac' | 'wav';
+        quality?: number;
+    };
+}
+export type AssetTransformMaterializeInput = {
+    definition: AssetTransformDefinition;
+    preset?: never;
+} | {
+    preset: string;
+    definition?: never;
+};
+export interface AssetDerivedAsset {
+    id: string;
+    asset_id: string;
+    source_checksum_sha256: string;
+    transform_hash: string;
+    normalized_spec: string;
+    definition_version: number;
+    output_kind: AssetTransformOutputKind;
+    dependency_checksum_sha256?: string;
+    processor_revision: string;
+    mime_type: string;
+    size: number;
+    status: string;
+    created_at: string;
+    updated_at: string;
+    last_accessed_at?: string;
+}
+export interface AssetImageGenerationInput {
+    prompt: string;
+    size: string;
+    format: 'png' | 'jpeg' | 'webp';
+    bucket: string;
+    key?: string;
+}

package/dist/asset-media-v2.js

@@ -0,0 +1 @@
+export {};

package/dist/asset-workflows.d.ts

@@ -0,0 +1,269 @@
+import type { StackShift } from './client.js';
+export interface AssetWorkflowDefinition {
+    version: 1;
+    nodes: AssetWorkflowNode[];
+    edges: AssetWorkflowEdge[];
+}
+export interface AssetWorkflowNode {
+    id: string;
+    type: string;
+    action?: string;
+    action_version?: string;
+    config?: Record<string, unknown>;
+    retry?: {
+        max_attempts?: number;
+        backoff_seconds?: number;
+    };
+    timeout_seconds?: number;
+    failure_policy?: string;
+}
+export interface AssetWorkflowEdge {
+    id: string;
+    source: string;
+    source_port?: string;
+    target: string;
+    target_port?: string;
+}
+export interface AssetWorkflowLayout {
+    nodes: Array<{
+        id: string;
+        x: number;
+        y: number;
+        width?: number;
+        height?: number;
+    }>;
+    viewport: {
+        x: number;
+        y: number;
+        zoom: number;
+    };
+    groups?: Array<{
+        id: string;
+        label: string;
+        node_ids: string[];
+    }>;
+}
+export interface AssetWorkflow {
+    id: string;
+    name: string;
+    description?: string;
+    status: 'draft' | 'active' | 'disabled';
+    revision: number;
+    execution_principal_id: string;
+    draft_definition: AssetWorkflowDefinition;
+    draft_layout: AssetWorkflowLayout;
+    current_version_id?: string;
+    active_version_id?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface AssetWorkflowVersion {
+    id: string;
+    workflow_id: string;
+    version: number;
+    semantic_digest: string;
+    definition: AssetWorkflowDefinition;
+    layout: AssetWorkflowLayout;
+    created_by: string;
+    created_at: string;
+}
+export interface AssetWorkflowRun {
+    id: string;
+    workflow_id: string;
+    version_id: string;
+    durable_run_id?: string;
+    trigger_type: string;
+    trigger_key?: string;
+    status: 'queued' | 'running' | 'waiting' | 'completed' | 'completed_with_warning' | 'failed' | 'canceled';
+    input: unknown;
+    output?: unknown;
+    error?: unknown;
+    started_at?: string;
+    completed_at?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface AssetWorkflowNodeExecution {
+    id: string;
+    run_id: string;
+    node_id: string;
+    node_type: string;
+    status: string;
+    attempt: number;
+    input?: unknown;
+    output?: unknown;
+    error?: unknown;
+    selected_ports: string[];
+    wait_event?: string;
+    wait_correlation?: string;
+    wait_until?: string;
+    started_at?: string;
+    completed_at?: string;
+    stackie_activity?: Array<Record<string, unknown>>;
+}
+export interface AssetWorkflowValidation {
+    valid: boolean;
+    semantic_digest?: string;
+    definition: AssetWorkflowDefinition;
+    issues: Array<{
+        code: string;
+        message: string;
+        node_id?: string;
+        edge_id?: string;
+    }>;
+}
+export interface AssetWorkflowNodeDefinition {
+    type: string;
+    version: string;
+    name: string;
+    category: string;
+    description: string;
+    input_ports: Array<{
+        name: string;
+        data_type: string;
+        required?: boolean;
+    }>;
+    output_ports: Array<{
+        name: string;
+        data_type: string;
+        required?: boolean;
+    }>;
+    config_schema: Record<string, unknown>;
+    risk: 'read' | 'reversible' | 'costly' | 'production' | 'external';
+    requires_approval: boolean;
+    approval_mode: 'none' | 'version' | 'per_run';
+}
+export interface AssetWorkflowTemplate {
+    key: string;
+    name: string;
+    description: string;
+    definition: AssetWorkflowDefinition;
+    layout: AssetWorkflowLayout;
+    valid: boolean;
+    issues: AssetWorkflowValidation['issues'];
+}
+export interface AssetWorkflowApproval {
+    id: string;
+    workflow_id: string;
+    version_id: string;
+    run_id?: string;
+    node_id?: string;
+    approval_mode: 'version' | 'per_run';
+    semantic_digest: string;
+    status: 'pending' | 'approved' | 'rejected';
+    risk_summary: unknown;
+    constraints: unknown;
+    requested_by: string;
+    decided_by?: string;
+    decision_reason?: string;
+    expires_at?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface AssetWorkflowHTTPConnection {
+    id?: string;
+    name: string;
+    host: string;
+    allowed_path_prefixes: string[];
+    credential_reference?: string;
+    credential?: AssetWorkflowHTTPCredentialInput;
+    default_headers: Record<string, string>;
+    revision?: number;
+    created_at?: string;
+    updated_at?: string;
+}
+export interface AssetWorkflowHTTPCredentialInput {
+    name: string;
+    header: string;
+    prefix?: string;
+    value: string;
+}
+export interface AssetAutomationOverview {
+    mcp_endpoint: '/api/v1/assets/mcp';
+    auth_method: 'pat';
+    tools: Array<{
+        name: string;
+        description: string;
+        required_scope: string;
+        required_scopes?: string[];
+        risk: string;
+    }>;
+    recent_executions: Array<{
+        id: string;
+        tool: string;
+        transport: string;
+        status: string;
+        created_at: string;
+    }>;
+}
+export declare class AssetWorkflowsClient {
+    private readonly client;
+    constructor(client: StackShift);
+    catalog(): Promise<{
+        nodes: AssetWorkflowNodeDefinition[];
+        templates: AssetWorkflowTemplate[];
+    }>;
+    create(input: {
+        name: string;
+        description?: string;
+        template_key?: string;
+        definition?: AssetWorkflowDefinition;
+        layout?: AssetWorkflowLayout;
+    }): Promise<AssetWorkflow>;
+    list(page?: number, perPage?: number): Promise<AssetWorkflow[]>;
+    get(workflowId: string): Promise<AssetWorkflow>;
+    updateDraft(workflowId: string, input: {
+        name: string;
+        description?: string;
+        definition: AssetWorkflowDefinition;
+        layout: AssetWorkflowLayout;
+        expected_revision: number;
+    }): Promise<AssetWorkflow>;
+    validate(workflowId: string): Promise<AssetWorkflowValidation>;
+    publish(workflowId: string, expectedRevision: number): Promise<AssetWorkflowVersion>;
+    activate(workflowId: string, versionId: string, expectedRevision: number): Promise<void>;
+    versions(workflowId: string): Promise<AssetWorkflowVersion[]>;
+    run(workflowId: string, input?: {
+        version_id?: string;
+        input?: unknown;
+        idempotency_key?: string;
+    }): Promise<AssetWorkflowRun>;
+    runs(workflowId: string, page?: number, perPage?: number): Promise<AssetWorkflowRun[]>;
+    runDetail(runId: string): Promise<{
+        run: AssetWorkflowRun;
+        nodes: AssetWorkflowNodeExecution[];
+    }>;
+    cancelRun(runId: string): Promise<AssetWorkflowRun>;
+    retryRun(runId: string): Promise<AssetWorkflowRun>;
+    approvals(status?: AssetWorkflowApproval['status']): Promise<AssetWorkflowApproval[]>;
+    decideApproval(approvalId: string, approved: boolean, input?: {
+        reason?: string;
+        expires_at?: string;
+    }): Promise<AssetWorkflowApproval>;
+    approve(approvalId: string, input?: {
+        reason?: string;
+        expires_at?: string;
+    }): Promise<AssetWorkflowApproval>;
+    reject(approvalId: string, input?: {
+        reason?: string;
+    }): Promise<AssetWorkflowApproval>;
+    connections(): Promise<AssetWorkflowHTTPConnection[]>;
+    createConnection(input: AssetWorkflowHTTPConnection): Promise<AssetWorkflowHTTPConnection>;
+    rotateConnectionCredential(connectionId: string, input: AssetWorkflowHTTPCredentialInput): Promise<{
+        id: string;
+        name: string;
+        header: string;
+        prefix?: string;
+        revision: number;
+    }>;
+    rotateInboundHook(workflowId: string): Promise<{
+        hook: {
+            id: string;
+            workflow_id: string;
+            secret_version: number;
+            enabled: boolean;
+        };
+        token: string;
+        secret: string;
+    }>;
+}

package/dist/asset-workflows.js

@@ -0,0 +1,69 @@
+export class AssetWorkflowsClient {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    catalog() {
+        return this.client.request('/assets/workflows/catalog');
+    }
+    create(input) {
+        return this.client.request('/assets/workflows', { method: 'POST', body: input });
+    }
+    list(page = 1, perPage = 20) {
+        return this.client.request(`/assets/workflows?page=${page}&per_page=${perPage}`);
+    }
+    get(workflowId) { return this.client.request(`/assets/workflows/${encodeURIComponent(workflowId)}`); }
+    updateDraft(workflowId, input) {
+        return this.client.request(`/assets/workflows/${encodeURIComponent(workflowId)}/draft`, { method: 'PUT', body: input });
+    }
+    validate(workflowId) {
+        return this.client.request(`/assets/workflows/${encodeURIComponent(workflowId)}/validate`, { method: 'POST' });
+    }
+    publish(workflowId, expectedRevision) {
+        return this.client.request(`/assets/workflows/${encodeURIComponent(workflowId)}/publish`, { method: 'POST', body: { expected_revision: expectedRevision } });
+    }
+    activate(workflowId, versionId, expectedRevision) {
+        return this.client.request(`/assets/workflows/${encodeURIComponent(workflowId)}/activate`, { method: 'POST', body: { version_id: versionId, expected_revision: expectedRevision } });
+    }
+    versions(workflowId) { return this.client.request(`/assets/workflows/${encodeURIComponent(workflowId)}/versions`); }
+    run(workflowId, input = {}) {
+        return this.client.request(`/assets/workflows/${encodeURIComponent(workflowId)}/run`, {
+            method: 'POST', body: input,
+            headers: input.idempotency_key ? { 'Idempotency-Key': input.idempotency_key } : undefined,
+        });
+    }
+    runs(workflowId, page = 1, perPage = 20) {
+        return this.client.request(`/assets/workflows/${encodeURIComponent(workflowId)}/runs?page=${page}&per_page=${perPage}`);
+    }
+    runDetail(runId) {
+        return this.client.request(`/assets/workflows/runs/${encodeURIComponent(runId)}`);
+    }
+    cancelRun(runId) {
+        return this.client.request(`/assets/workflows/runs/${encodeURIComponent(runId)}/cancel`, { method: 'POST' });
+    }
+    retryRun(runId) {
+        return this.client.request(`/assets/workflows/runs/${encodeURIComponent(runId)}/retry`, { method: 'POST' });
+    }
+    approvals(status) {
+        if (status)
+            return this.client.request(`/assets/workflows/approvals?status=${encodeURIComponent(status)}`);
+        return this.client.request('/assets/workflows/approvals');
+    }
+    decideApproval(approvalId, approved, input = {}) {
+        return approved ? this.approve(approvalId, input) : this.reject(approvalId, input);
+    }
+    approve(approvalId, input = {}) {
+        return this.client.request(`/assets/workflows/approvals/${encodeURIComponent(approvalId)}/approve`, { method: 'POST', body: input });
+    }
+    reject(approvalId, input = {}) {
+        return this.client.request(`/assets/workflows/approvals/${encodeURIComponent(approvalId)}/reject`, { method: 'POST', body: input });
+    }
+    connections() { return this.client.request('/assets/workflows/connections'); }
+    createConnection(input) { return this.client.request('/assets/workflows/connections', { method: 'POST', body: input }); }
+    rotateConnectionCredential(connectionId, input) {
+        return this.client.request(`/assets/workflows/connections/${encodeURIComponent(connectionId)}/credential/rotate`, { method: 'POST', body: input });
+    }
+    rotateInboundHook(workflowId) {
+        return this.client.request(`/assets/workflows/${encodeURIComponent(workflowId)}/inbound-hook/rotate`, { method: 'POST' });
+    }
+}