@stackshift-cloud/sdk 1.0.0 → 1.1.0

package/README.md

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

package/dist/assets-platform-types.d.ts

@@ -0,0 +1,218 @@
+import type { Asset, AssetBucket, JsonValue } from './types.js';
+export type AssetConnectionProvider = 'aws_s3' | 'r2' | 'wasabi' | 'minio' | 's3' | 'stackshift_s2' | 'cloudinary';
+export type AssetConnectionStatus = 'unverified' | 'verified' | 'failed' | 'revoked';
+export type AssetStorageMode = 'managed' | 'byob' | 'stackshift_s2';
+export type AssetMigrationStatus = 'queued' | 'running' | 'completed' | 'failed' | 'canceled';
+export type AssetMigrationItemStatus = 'queued' | 'running' | 'imported' | 'skipped' | 'failed' | 'canceled';
+export interface AssetConnection {
+    id: string;
+    provider: AssetConnectionProvider;
+    name: string;
+    configuration: Record<string, JsonValue>;
+    external_id: string;
+    s2_bucket_id?: string;
+    status: AssetConnectionStatus;
+    last_verified_at?: string;
+    verification_error?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface AssetS3ConnectionConfiguration {
+    bucket: string;
+    region?: string;
+    endpoint?: string;
+    prefix?: string;
+    role_arn?: string;
+    auth_type: 'assume_role' | 'static';
+    path_style?: boolean;
+}
+export interface AssetS3StaticCredentials {
+    access_key_id: string;
+    secret_access_key: string;
+    session_token?: string;
+}
+export interface AssetCloudinaryConfiguration {
+    cloud_name: string;
+    api_key: string;
+}
+export interface AssetCloudinaryCredentials {
+    api_secret: string;
+}
+interface AssetConnectionInputBase {
+    name: string;
+}
+export type AssetConnectionInput = AssetConnectionInputBase & ({
+    provider: 'aws_s3';
+    configuration: AssetS3ConnectionConfiguration;
+    credentials?: AssetS3StaticCredentials;
+} | {
+    provider: 'r2' | 'wasabi' | 'minio' | 's3';
+    configuration: AssetS3ConnectionConfiguration;
+    credentials: AssetS3StaticCredentials;
+} | {
+    provider: 'cloudinary';
+    configuration: AssetCloudinaryConfiguration;
+    credentials: AssetCloudinaryCredentials;
+} | {
+    provider: 'stackshift_s2';
+    s2_bucket_id: string;
+    configuration?: never;
+    credentials?: never;
+});
+export interface AssetStorageConfiguration {
+    storage_mode: AssetStorageMode;
+    connection_id?: string;
+    s2_bucket_id?: string;
+    object_prefix?: string;
+    derivative_prefix?: string;
+    auto_extract_text?: boolean;
+    expected_revision?: number;
+}
+export interface AssetS2Bucket {
+    id: string;
+    name: string;
+    workspace_id?: string;
+    project_id?: string;
+    region: string;
+    visibility: string;
+    versioning_enabled: boolean;
+    quota_bytes?: number;
+    object_count: number;
+    size_bytes: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface AssetMigrationInput {
+    kind?: 'import' | 'relocate';
+    source_connection_id?: string;
+    destination_bucket_id: string;
+    source_prefix?: string;
+    conflict_policy?: 'skip' | 'new_version' | 'rename';
+    dry_run?: boolean;
+}
+export interface AssetMigration {
+    id: string;
+    kind: 'import' | 'relocate';
+    source_connection_id?: string;
+    destination_bucket_id: string;
+    source_prefix: string;
+    conflict_policy: 'skip' | 'new_version' | 'rename';
+    dry_run: boolean;
+    status: AssetMigrationStatus;
+    phase: 'inventory' | 'transfer' | 'complete' | string;
+    total_items: number;
+    processed_items: number;
+    imported_items: number;
+    skipped_items: number;
+    failed_items: number;
+    total_bytes: number;
+    processed_bytes: number;
+    report: Record<string, JsonValue>;
+    cancel_requested_at?: string;
+    started_at?: string;
+    completed_at?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface AssetMigrationItem {
+    id: string;
+    migration_id: string;
+    source_identity: string;
+    source_key: string;
+    destination_key: string;
+    content_type?: string;
+    size?: number;
+    checksum_sha256?: string;
+    checksum_state: 'known' | 'pending_execution' | 'verified';
+    source_metadata: Record<string, JsonValue>;
+    source_tags: string[];
+    status: AssetMigrationItemStatus;
+    attempt_count: number;
+    max_attempts: number;
+    mapped_asset_id?: string;
+    warning_code?: string;
+    error_code?: string;
+    error_message?: string;
+    created_at: string;
+    updated_at: string;
+    finished_at?: string;
+}
+export interface AssetTextBlock {
+    text: string;
+    type: string;
+    confidence: number;
+    box: [number, number, number, number];
+}
+export interface AssetTextPage {
+    number: number;
+    width: number;
+    height: number;
+    blocks: AssetTextBlock[];
+}
+export interface AssetTextExtraction {
+    id: string;
+    checksum_sha256: string;
+    provider: string;
+    engine_version: string;
+    language: string;
+    options_hash: string;
+    status: 'pending' | 'processing' | 'ready' | 'failed';
+    plain_text?: string;
+    pages: AssetTextPage[];
+    page_count: number;
+    error_code?: string;
+    error_message?: string;
+    created_at: string;
+    updated_at: string;
+    completed_at?: string;
+}
+export interface AssetUploadCapabilityInput {
+    bucket: string;
+    key_prefix?: string;
+    fixed_key?: string;
+    allowed_mime_types?: string[];
+    allowed_origins: string[];
+    max_bytes: number;
+    allow_remote_url?: boolean;
+    expires_in: string;
+}
+export interface AssetUploadCapability {
+    id: string;
+    bucket: string;
+    key_prefix: string;
+    fixed_key?: string;
+    allowed_mime_types: string[];
+    allowed_origins: string[];
+    max_bytes: number;
+    allow_remote_url: boolean;
+    session_id?: string;
+    expires_at: string;
+    created_at: string;
+}
+export interface CreatedAssetUploadCapability {
+    capability: AssetUploadCapability;
+    token: string;
+}
+export interface AssetMigrationListResult {
+    migrations: AssetMigration[];
+}
+export interface AssetConnectionListResult {
+    connections: AssetConnection[];
+}
+export interface AssetS2BucketListResult {
+    buckets: AssetS2Bucket[];
+}
+export interface AssetRelocationInput {
+    dry_run?: boolean;
+}
+export interface AssetTextExtractionInput {
+    language?: string;
+    options?: Record<string, JsonValue>;
+}
+export type AssetMigrationReport = {
+    migration: AssetMigration;
+    items: AssetMigrationItem[];
+} | Record<string, JsonValue>;
+export type AssetCapabilityUploadResult = Asset;
+export type AssetStorageBucket = AssetBucket;
+export {};

package/dist/assets-platform-types.js

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