@stackshift-cloud/sdk 1.3.0 → 1.3.1

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

@@ -209,10 +209,27 @@ export interface AssetTextExtractionInput {
     language?: string;
     options?: Record<string, JsonValue>;
 }
-export type AssetMigrationReport = {
+export interface AssetMigrationReconciliation {
+    discovered: number;
+    imported: number;
+    skipped: number;
+    failed: number;
+    canceled: number;
+    unresolved: number;
+    mapped: number;
+    verified_checksums: number;
+    missing_checksums: number;
+    warnings: Record<string, number>;
+    inventory_reconciled: boolean;
+    delivery_verified: boolean;
+    cutover_ready: boolean;
+    next_actions: string[];
+}
+export interface AssetMigrationReport {
     migration: AssetMigration;
     items: AssetMigrationItem[];
-} | Record<string, JsonValue>;
+    reconciliation?: AssetMigrationReconciliation;
+}
 export type AssetCapabilityUploadResult = Asset;
 export type AssetStorageBucket = AssetBucket;
 export {};

package/dist/index.d.ts

@@ -6,6 +6,10 @@ export type * from './asset-media-v2.js';
 export { AssetConnectionsClient, AssetMigrationsClient, AssetStorageClient, AssetTextClient, AssetUploadCapabilitiesClient } from './assets-platform.js';
 export type * from './assets-platform-types.js';
 export { ChunkedUploadController, UploadResumeInvalidError, putBlob, sha256Blob } from './upload-controller.js';
+export { S2UploadsClient } from './s2.js';
+export type { S2Object } from './s2.js';
+export { S2Uploader, createS2ResumeStore } from './s2-upload.js';
+export type { S2UploadBackend } from './s2-upload.js';
 export type { ChunkUploadCallbacks, ChunkUploadRequest, ChunkUploadSession, ChunkUploadTransport, ChunkedUploadOptions, UploadProgress, UploadResumeRecord, UploadResumeStore, UploadedPart } from './upload-controller.js';
 export { createResponsiveImage, namedResponsiveSource, uploadBrowserFile } from './assets-framework.js';
 export type { ArtDirectionSource, ResponsiveImageDescriptor, ResponsiveImageOptions } from './assets-framework.js';
@@ -26,7 +30,7 @@ export type { MailSendTemplateInput, MailSendTemplateResponse, MailTemplate, Mai
 export type { MailEvent, MailEventListOptions, MailEventListResult, MailEventType, MailTimelineItem, MailWebhook, MailWebhookCreateInput, MailWebhookCreateResponse, MailWebhookDelivery, MailWebhookDeliveryAttempt, MailWebhookDeliveryDetail, MailWebhookDeliveryListOptions, MailWebhookListOptions, MailWebhookListResult, MailWebhookUpdateInput, MailWebhookReplay, MailWebhookReplayInput, } from './mail-webhook-types.js';
 export type { MailMessageStream, MailMessageStreamCreateInput, MailMessageStreamListResult } from './mail-streams.js';
 export type { MailDomainReputation, MailLimits, MailManualReviewStatus, MailReputation, MailReputationEvent, MailReputationEventListOptions, MailReputationEventListResult, MailReputationEventSeverity, MailReputationStatus, MailReputationTier, MailReputationWorkspace, } from './mail-reputation-types.js';
-export type { MailAnalytics, MailAnalyticsInput, MailAttachmentInput, MailBatch, MailBatchItem, MailBatchSendInput, MailBatchTemplateInput, MailInboundDomain, MailInboundMessage, MailScheduledCreateInput, MailScheduledMessage, } from './mail-advanced-types.js';
+export type { MailAnalytics, MailAnalyticsRateCohort, MailAnalyticsInput, MailAttachmentInput, MailBatch, MailBatchItem, MailBatchSendInput, MailBatchTemplateInput, MailInboundDomain, MailInboundMessage, MailScheduledCreateInput, MailScheduledMessage, } from './mail-advanced-types.js';
 export { AssetVideoClient } from './assets-video.js';
 export type * from './assets-video-types.js';
 export * from './mail-tracking.js';

package/dist/index.js

@@ -3,6 +3,8 @@ export { AssetsClient, assetTransformOptions, assetTransformPresets, assetTransf
 export { AssetWorkflowsClient } from './asset-workflows.js';
 export { AssetConnectionsClient, AssetMigrationsClient, AssetStorageClient, AssetTextClient, AssetUploadCapabilitiesClient } from './assets-platform.js';
 export { ChunkedUploadController, UploadResumeInvalidError, putBlob, sha256Blob } from './upload-controller.js';
+export { S2UploadsClient } from './s2.js';
+export { S2Uploader, createS2ResumeStore } from './s2-upload.js';
 export { createResponsiveImage, namedResponsiveSource, uploadBrowserFile } from './assets-framework.js';
 export { assetContractOperations } from './generated/assets-contract.js';
 export { MailBouncesClient, MailClient, MailDomainsClient, MailEventsClient, MailLimitsClient, MailMessagesClient, MailScheduledClient, MailBatchClient, MailInboundClient, MailAnalyticsClient, MailOtpChallengesClient, MailOtpClient, MailReputationClient, MailReputationEventsClient, MailSuppressionsClient, MailTemplatesClient, MailWebhooksClient, MailStreamsClient, MailAudiencesClient, MailCampaignsClient, } from './mail.js';

package/dist/mail-advanced-types.d.ts

@@ -107,7 +107,18 @@ export interface MailAnalyticsInput {
     template?: string;
     event?: string;
 }
+export interface MailAnalyticsRateCohort {
+    basis: 'recipient_created_at';
+    asOf: string;
+    queued: number;
+    mtaAccepted: number;
+    delivered: number;
+    bounced: number;
+    failed: number;
+}
 export interface MailAnalytics {
+    rateCohort?: MailAnalyticsRateCohort;
+    previousRateCohort?: MailAnalyticsRateCohort;
     summary: Record<string, number>;
     series: Array<Record<string, number | string>>;
 }

package/dist/mail-billing.d.ts

@@ -1,6 +1,10 @@
 import type { StackShift } from './client.js';
 import type { MailMode } from './mail-simulation.js';
 export interface MailBillingSummary {
+    catalogId?: string;
+    planSlug?: string;
+    monthlyPriceKobo?: number;
+    overageAllowed?: boolean;
     reconciliationRequired: boolean;
     active: boolean;
     mode: MailMode;

package/dist/mail-marketing.d.ts

@@ -56,12 +56,19 @@ export declare class MailFormsClient {
         data: MailSignupForm[];
     }>;
 }
+export interface MailSegmentCondition {
+    field: string;
+    operator: 'equals' | 'not_equals' | 'contains' | 'exists';
+    value?: string;
+}
 export interface MailSegmentInput {
+    match?: 'all' | 'any';
+    conditions?: MailSegmentCondition[];
     audienceId: string;
     name: string;
     description?: string;
-    field: string;
-    operator: string;
+    field?: string;
+    operator?: string;
     value?: string;
 }
 export interface MailSegment extends MailSegmentInput {

package/dist/s2-upload.d.ts

@@ -0,0 +1,22 @@
+import type { ChunkUploadRequest, ChunkUploadSession, ChunkedUploadOptions, UploadedPart, UploadResumeStore } from './upload-controller.js';
+export interface S2UploadBackend<TResult> {
+    create(input: ChunkUploadRequest & {
+        size: number;
+    }): Promise<ChunkUploadSession>;
+    resume(context: string): Promise<ChunkUploadSession>;
+    signPart(session: ChunkUploadSession, part: UploadedPart): Promise<{
+        url: string;
+        headers?: Record<string, string>;
+    }>;
+    complete(session: ChunkUploadSession): Promise<TResult>;
+    cancel(session: ChunkUploadSession): Promise<void>;
+}
+/** Bind these callbacks to authenticated application-server routes. Never put permanent S3 credentials in a browser. */
+export declare class S2Uploader<TResult> {
+    private readonly controller;
+    constructor(backend: S2UploadBackend<TResult>, store?: UploadResumeStore);
+    upload(file: Blob, request: ChunkUploadRequest, options?: ChunkedUploadOptions): Promise<TResult>;
+    cancel(resumeKey: string): Promise<void>;
+}
+/** Use an account-specific namespace, and clear it on logout. Stored sessions contain temporary upload capabilities. */
+export declare function createS2ResumeStore(storage: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>, namespace: string): UploadResumeStore;

package/dist/s2-upload.js

@@ -0,0 +1,49 @@
+import { ChunkedUploadController, putBlob } from './upload-controller.js';
+/** Bind these callbacks to authenticated application-server routes. Never put permanent S3 credentials in a browser. */
+export class S2Uploader {
+    controller;
+    constructor(backend, store) {
+        this.controller = new ChunkedUploadController({
+            create: (file, request) => backend.create({ ...request, size: file.size }),
+            resume: (context) => backend.resume(context),
+            uploadPart: async (session, partNumber, chunk, checksumSHA256, callbacks) => {
+                const signed = await backend.signPart(session, { partNumber, size: chunk.size, checksumSHA256 });
+                await putBlob(signed.url, chunk, callbacks, signed.headers);
+            },
+            complete: (session) => backend.complete(session),
+            cancel: (session) => backend.cancel(session),
+        }, store);
+    }
+    upload(file, request, options = {}) {
+        if (file.size === 0)
+            return Promise.reject(new Error('Use a single presigned PUT for an empty object'));
+        return this.controller.upload(file, request, { ...options, requireMatchingFile: true });
+    }
+    cancel(resumeKey) { return this.controller.cancel(resumeKey); }
+}
+/** Use an account-specific namespace, and clear it on logout. Stored sessions contain temporary upload capabilities. */
+export function createS2ResumeStore(storage, namespace) {
+    if (!namespace.trim())
+        throw new Error('An account-specific upload namespace is required');
+    const key = (value) => `stackshift:s2:${encodeURIComponent(namespace)}:${encodeURIComponent(value)}`;
+    return {
+        async get(value) {
+            const raw = storage.getItem(key(value));
+            if (raw === null)
+                return undefined;
+            let record;
+            try {
+                record = JSON.parse(raw);
+            }
+            catch {
+                throw new Error('Saved upload state is unreadable; clear it before starting again');
+            }
+            if (!record || record.key !== value || typeof record.fingerprint !== 'string' || !record.session?.id) {
+                throw new Error('Saved upload state is invalid; clear it before starting again');
+            }
+            return record;
+        },
+        async set(record) { storage.setItem(key(record.key), JSON.stringify(record)); },
+        async delete(value) { storage.removeItem(key(value)); },
+    };
+}

package/dist/s2.d.ts

@@ -0,0 +1,34 @@
+import type { StackShift } from './client.js';
+import type { S2UploadBackend } from './s2-upload.js';
+import type { ChunkUploadSession, UploadedPart } from './upload-controller.js';
+export interface S2Object {
+    id: string;
+    version_id: string;
+    bucket_id: string;
+    key: string;
+    size: number;
+    etag: string;
+    checksum_sha256: string;
+    content_type: string;
+}
+/** Server-side adapter. Authorize the application's user and destination before forwarding browser requests. */
+export declare class S2UploadsClient implements S2UploadBackend<S2Object> {
+    private readonly client;
+    private readonly path;
+    constructor(client: StackShift, bucketID: string);
+    create(input: {
+        key: string;
+        size: number;
+        mimeType: string;
+    }): Promise<ChunkUploadSession>;
+    resume(context: string): Promise<ChunkUploadSession>;
+    signPart(session: ChunkUploadSession, part: UploadedPart): Promise<{
+        url: string;
+        headers: {
+            [k: string]: string;
+        };
+    }>;
+    complete(session: ChunkUploadSession): Promise<S2Object>;
+    cancel(session: ChunkUploadSession): Promise<void>;
+    private action;
+}

package/dist/s2.js

@@ -0,0 +1,31 @@
+/** Server-side adapter. Authorize the application's user and destination before forwarding browser requests. */
+export class S2UploadsClient {
+    client;
+    path;
+    constructor(client, bucketID) {
+        this.client = client;
+        if (!bucketID)
+            throw new Error('A bucket ID is required');
+        this.path = `/buckets/${encodeURIComponent(bucketID)}/uploads`;
+    }
+    create(input) {
+        return this.client.request(this.path, { method: 'POST', body: input });
+    }
+    resume(context) {
+        return this.action('resume', context);
+    }
+    async signPart(session, part) {
+        const result = await this.action('sign-part', session.uploadToken, part);
+        const headers = Object.fromEntries(Object.entries(result.headers ?? {}).map(([name, values]) => [name, values.join(', ')]));
+        return { url: result.url, headers };
+    }
+    complete(session) {
+        return this.action('complete', session.uploadToken);
+    }
+    async cancel(session) {
+        await this.action('cancel', session.uploadToken);
+    }
+    action(action, token, part) {
+        return this.client.request(`${this.path}/actions`, { method: 'POST', body: { action, token, part } });
+    }
+}

package/dist/types.d.ts

@@ -197,6 +197,18 @@ export interface ProjectListOptions {
     perPage?: number;
 }
 export interface Asset {
+    readiness?: {
+        state: "ready" | "processing" | "blocked" | "unknown";
+        stages: Array<{
+            id: string;
+            status: string;
+        }>;
+        actions: Record<"preview" | "download" | "edit" | "publish", {
+            state: "ready" | "blocked" | "unknown";
+            code: string;
+            message: string;
+        }>;
+    };
     id: string;
     bucket: string;
     key: string;

package/dist/upload-controller.d.ts

@@ -9,6 +9,7 @@ export interface UploadedPart {
     checksumSHA256?: string;
 }
 export interface ChunkUploadSession {
+    completionPending?: boolean;
     id: string;
     uploadToken: string;
     expiresAt: string;
@@ -52,6 +53,7 @@ export interface ChunkedUploadOptions extends ChunkUploadCallbacks {
     concurrency?: number;
     retryAttempts?: number;
     cancelOnAbort?: boolean;
+    requireMatchingFile?: boolean;
 }
 export declare class UploadResumeInvalidError extends Error {
     constructor(message?: string);

package/dist/upload-controller.js

@@ -16,13 +16,13 @@ export class ChunkedUploadController {
         throwIfAborted(options.signal);
         const resumeKey = options.resumeKey;
         const fingerprint = fileFingerprint(file, request);
-        let session = await this.restore(resumeKey, fingerprint);
+        let session = await this.restore(resumeKey, fingerprint, options.requireMatchingFile);
         if (!session)
             session = await this.transport.create(file, request);
         validateSession(session, file.size);
         options.onSession?.(session);
         await this.persist(resumeKey, fingerprint, session);
-        const completed = await verifiedCompletedParts(file, session);
+        const completed = await verifiedCompletedParts(file, session, options.requireMatchingFile);
         const loadedByPart = new Map(completed);
         const tasks = [];
         for (let offset = 0, partNumber = 1; offset < file.size; offset += session.partSize, partNumber += 1) {
@@ -37,8 +37,9 @@ export class ChunkedUploadController {
         const concurrency = boundedInteger(options.concurrency, 4, 1, 8);
         const attempts = boundedInteger(options.retryAttempts, 4, 1, 8);
         let next = 0;
+        let workerFailed = false;
         const worker = async () => {
-            while (next < tasks.length) {
+            while (!workerFailed && next < tasks.length) {
                 throwIfAborted(options.signal);
                 const task = tasks[next++];
                 const checksum = await sha256Blob(task.chunk);
@@ -61,7 +62,16 @@ export class ChunkedUploadController {
             }
         };
         try {
-            await Promise.all(Array.from({ length: Math.min(concurrency, tasks.length || 1) }, worker));
+            const workers = await Promise.allSettled(Array.from({ length: Math.min(concurrency, tasks.length || 1) }, () => worker().catch((error) => {
+                workerFailed = true;
+                throw error;
+            })));
+            const failed = workers.find((result) => result.status === 'rejected');
+            if (failed?.status === 'rejected')
+                throw failed.reason;
+            throwIfAborted(options.signal);
+            session.completionPending = true;
+            await this.persist(resumeKey, fingerprint, session);
             const result = await retryWithBackoff(() => this.transport.complete(session), attempts, options.signal);
             if (resumeKey)
                 await this.store?.delete(resumeKey);
@@ -69,9 +79,12 @@ export class ChunkedUploadController {
         }
         catch (error) {
             if (isAbortError(error) && options.cancelOnAbort) {
-                await this.transport.cancel(session).catch(() => undefined);
-                if (resumeKey)
-                    await this.store?.delete(resumeKey);
+                try {
+                    await this.transport.cancel(session);
+                    if (resumeKey)
+                        await this.store?.delete(resumeKey);
+                }
+                catch { /* Retain recovery state when remote cancellation is uncertain. */ }
             }
             throw error;
         }
@@ -80,19 +93,24 @@ export class ChunkedUploadController {
         const record = await this.store?.get(resumeKey);
         if (!record)
             return;
-        try {
-            await this.transport.cancel(record.session);
-        }
-        finally {
-            await this.store?.delete(resumeKey);
-        }
+        await this.transport.cancel(record.session);
+        await this.store?.delete(resumeKey);
     }
-    async restore(resumeKey, fingerprint) {
+    async restore(resumeKey, fingerprint, requireMatchingFile = false) {
         if (!resumeKey || !this.store)
             return undefined;
         const record = await this.store.get(resumeKey);
         if (!record)
             return undefined;
+        if (record.fingerprint !== fingerprint && requireMatchingFile) {
+            throw new Error('Reselect the original file to resume this upload, or cancel the saved upload first');
+        }
+        if (record.fingerprint === fingerprint && record.session.completionPending) {
+            if (Date.parse(record.session.expiresAt) <= Date.now()) {
+                throw new Error('Completion is uncertain and its recovery window expired; verify the destination before clearing saved state');
+            }
+            return record.session;
+        }
         if (record.fingerprint !== fingerprint || Date.parse(record.session.expiresAt) <= Date.now()) {
             await this.transport.cancel(record.session).catch(() => undefined);
             await this.store.delete(resumeKey);
@@ -117,7 +135,7 @@ export class ChunkedUploadController {
             session: { ...session, parts: session.parts.map((part) => ({ ...part })) },
             updatedAt: new Date().toISOString(),
         };
-        this.persistence = this.persistence.then(() => this.store.set(record));
+        this.persistence = this.persistence.catch(() => undefined).then(() => this.store.set(record));
         return this.persistence;
     }
 }
@@ -154,9 +172,10 @@ export async function sha256Blob(blob) {
     return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
 }
 function validateSession(session, size) {
-    if (!session.id || !session.uploadToken || session.partSize <= 0)
+    if (!session.id || !session.uploadToken || !Number.isSafeInteger(session.partSize) || session.partSize <= 0 ||
+        !Number.isSafeInteger(session.maxBytes) || session.maxBytes < 0 || !Array.isArray(session.parts))
         throw new Error('Upload session is incomplete');
-    if (Date.parse(session.expiresAt) <= Date.now())
+    if (!Number.isFinite(Date.parse(session.expiresAt)) || Date.parse(session.expiresAt) <= Date.now())
         throw new Error('Upload session has expired');
     if (size > session.maxBytes)
         throw new Error(`File exceeds upload limit of ${session.maxBytes} bytes`);
@@ -167,7 +186,7 @@ function expectedPartSize(fileSize, partSize, partNumber) {
         return -1;
     return Math.min(partSize, fileSize - offset);
 }
-async function verifiedCompletedParts(file, session) {
+async function verifiedCompletedParts(file, session, requireMatchingFile = false) {
     const completed = new Map();
     for (const part of session.parts) {
         const expectedSize = expectedPartSize(file.size, session.partSize, part.partNumber);
@@ -178,6 +197,9 @@ async function verifiedCompletedParts(file, session) {
         if (checksum.toLowerCase() === part.checksumSHA256.toLowerCase()) {
             completed.set(part.partNumber, part.size);
         }
+        else if (requireMatchingFile) {
+            throw new Error('The selected file differs from an uploaded part; reselect the original file or cancel this upload');
+        }
     }
     return completed;
 }
@@ -195,6 +217,7 @@ function boundedInteger(value, fallback, minimum, maximum) {
 async function retryWithBackoff(operation, attempts, signal) {
     let lastError;
     for (let attempt = 0; attempt < attempts; attempt += 1) {
+        throwIfAborted(signal);
         try {
             return await operation();
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackshift-cloud/sdk",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Official JavaScript and TypeScript SDK for StackShift.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node test/mail.test.mjs && node test/mail-simulation.test.mjs && node test/mail-platform.test.mjs && node test/mail-webhooks.test.mjs && node test/mail-advanced.test.mjs && node test/mail-tracking.test.mjs && node test/mail-subscribers.test.mjs && node test/mail-exports.test.mjs && node test/mail-diagnostics.test.mjs && node test/assets.test.mjs && node test/assets-platform.test.mjs && node test/assets-video.test.mjs && node test/assets-dam.test.mjs && node test/ai-credits.test.mjs"
+    "test": "npm run build && node test/mail.test.mjs && node test/mail-simulation.test.mjs && node test/mail-platform.test.mjs && node test/mail-webhooks.test.mjs && node test/mail-advanced.test.mjs && node test/mail-tracking.test.mjs && node test/mail-subscribers.test.mjs && node test/mail-exports.test.mjs && node test/mail-diagnostics.test.mjs && node test/assets.test.mjs && node test/assets-platform.test.mjs && node test/assets-video.test.mjs && node test/assets-dam.test.mjs && node test/ai-credits.test.mjs && node --test test/s2-upload.test.mjs"
   },
   "devDependencies": {
     "typescript": "^5.4.0"