@stackshift-cloud/sdk 0.1.4 → 1.1.0

package/README.md

@@ -44,16 +44,16 @@ const message = await stackshift.mail.send({
 console.log(message.id, message.status, message.idempotencyStatus)
 ```
 
-Inspect sent messages:
+Inspect MTA-accepted messages:
 
 ```ts
-const messages = await stackshift.mail.messages.list({ status: 'sent', limit: 20 })
+const messages = await stackshift.mail.messages.list({ status: 'mta_accepted', limit: 20 })
 const detail = await stackshift.mail.messages.get(messages.data[0].id)
 const attempts = await stackshift.mail.messages.attempts(detail.id)
 const logs = await stackshift.mail.messages.logs(detail.id)
 ```
 
-In this MVP, `sent` means the message was accepted by StackShift's outbound MTA. It does not mean inbox delivery, opens, clicks, or spam placement. A `sent` message can later become `bounced` if StackShift receives a delivery-status notification.
+`mta_accepted` means StackShift's outbound MTA accepted the message. `delivered` means the recipient MX accepted a recipient; it does not claim inbox placement or human receipt. Recipient records remain authoritative for mixed outcomes.
 
 ## Send a template
 
@@ -218,6 +218,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/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

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-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' });
+    }
+}