@deepraxis/sdk 0.1.0-dev.c6c496f → 0.1.0-dev.cdc78ae

package/dist/helpers/application-publish.d.ts

@@ -1,5 +1,5 @@
 import type { Praxis } from '../core/client.js';
-import type { ApplicationAssetsConfig, ApplicationBinding } from '../generated/types.gen.js';
+import type { ApplicationAssetsConfig, ApplicationBinding, ApplicationVersion } from '../generated/types.gen.js';
 export type AssetsConfig = ApplicationAssetsConfig;
 export interface PublishInput {
     /** 应用名；存在同名应用时复用。 */
@@ -20,16 +20,32 @@ export interface PublishInput {
     bindings?: ApplicationBinding[];
     /** 静态资源路由配置，原样传递。 */
     assets_config?: AssetsConfig;
+    /** Register an upload session to plan changes; do not upload content or publish. Requires an existing application. */
+    dryRun?: boolean;
+    /** Preserve current paths omitted from files. Defaults to false (whole-site replacement). */
+    keepExisting?: boolean;
     /** 是否等待部署完成，默认 true。 */
     wait?: boolean;
     /** 部署等待上限（毫秒），默认 120000。超时不会撤销部署。 */
     timeout_ms?: number;
 }
 export interface PublishResult {
+    /** True when a static-only publication matches the active version. */
+    unchanged?: boolean;
+    /** Current version when unchanged or planning an existing deployment. */
+    version?: ApplicationVersion;
+    /** dryRun compares against the active version; counts are distinct content hashes. */
+    plan?: {
+        added: string[];
+        changed: string[];
+        removed: string[];
+        upload_hashes: number;
+        existing_hashes: number;
+    };
     url: string;
     worker_id: string;
-    version_id: string;
-    deployment_id: string;
+    version_id: string | null;
+    deployment_id: string | null;
     status: string;
     created: boolean;
     /** 本次上传的不同内容 hash 数量。 */
@@ -37,5 +53,9 @@ export interface PublishResult {
     /** 服务端已存在的不同内容 hash 数量。 */
     reused: number;
 }
-/** Publish through the public SDK resources, including content-addressed incremental uploads. */
+/** Publish with whole-site replacement by default; keepExisting preserves omitted paths.
+ * dryRun registers an idempotent upload session (stores its manifest), but uploads no content and does not publish.
+ * The platform does not support gradual rollout. Roll back using workers.deployments.create with
+ * strategy: 'percentage', versions: [{ version_id: previousVersionId, percentage: 100 }], while artifacts are retained.
+ */
 export declare function publish(client: Pick<Praxis, 'application'>, input: PublishInput): Promise<PublishResult>;

package/dist/helpers/application-publish.js

@@ -8,8 +8,16 @@ function base64(bytes) {
     }
     return btoa(chunks.join(''));
 }
-/** Publish through the public SDK resources, including content-addressed incremental uploads. */
+/** Publish with whole-site replacement by default; keepExisting preserves omitted paths.
+ * dryRun registers an idempotent upload session (stores its manifest), but uploads no content and does not publish.
+ * The platform does not support gradual rollout. Roll back using workers.deployments.create with
+ * strategy: 'percentage', versions: [{ version_id: previousVersionId, percentage: 100 }], while artifacts are retained.
+ */
 export async function publish(client, input) {
+    const rolloutFields = ['gradual', 'gradualRollout', 'gradual_rollout', 'canary', 'rollout', 'percentage', 'percent', 'traffic', 'traffic_percentage', 'strategy', 'versions'];
+    if (Object.keys(input).some(key => rolloutFields.includes(key) || /percentage|percent|canary|gradual|rollout|灰度/i.test(key))) {
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: '平台不支持灰度 (gradual rollout is not supported). Roll back with praxis.application.workers.deployments.create({ path: { worker_id }, body: { strategy: "percentage", versions: [{ version_id: previousVersionId, percentage: 100 }] } }); the previous version artifacts must still be retained.' });
+    }
     const timeout = input.timeout_ms ?? 120_000;
     if (!Number.isFinite(timeout) || timeout < 0)
         throw new RangeError('timeout_ms must be non-negative and finite');
@@ -21,7 +29,7 @@ export async function publish(client, input) {
     const files = Object.entries(input.files);
     if (files.length > 100_000)
         throw new PraxisError({ code: 'LIMIT_EXCEEDED', message: 'At most 100000 asset paths can be published' });
-    const manifest = {};
+    let manifest = {};
     const contents = new Map();
     for (const [path, content] of files) {
         const normalized = path.startsWith('/') ? path : `/${path}`;
@@ -44,9 +52,51 @@ export async function publish(client, input) {
         }
     }
     const created = !worker;
+    if (!worker && input.dryRun)
+        throw new PraxisError({ code: 'NOT_FOUND', message: '请先创建应用 (create the application before dryRun)' });
     worker ??= await workers.create({ body: { name: input.name, subdomain: { enabled: true } } });
     const path = { worker_id: worker.id };
+    let currentVersion;
+    let currentDeployment;
+    let previous = {};
+    if (worker.praxis?.current_deployment_id) {
+        currentDeployment = await workers.deployments.retrieve({ path: { ...path, deployment_id: worker.praxis.current_deployment_id } });
+        const active = currentDeployment.versions[0];
+        if (!active)
+            throw new PraxisError({ code: 'INVALID_RESPONSE', message: 'Current deployment has no version' });
+        currentVersion = await workers.versions.retrieve({ path: { ...path, version_id: active.version_id } });
+        previous = (await workers.versions.assets.retrieveManifest({ path: { ...path, version_id: active.version_id } })).manifest;
+    }
+    // Keep the stored path order: the service hashes JSON.stringify(manifest), including property order.
+    // Reordered input with identical paths must still hash to the active version's manifest_hash.
+    manifest = {
+        ...Object.fromEntries(Object.entries(previous).filter(([key]) => input.keepExisting || Object.hasOwn(manifest, key))),
+        ...manifest,
+    };
+    if (Object.keys(manifest).length > 100_000)
+        throw new PraxisError({ code: 'LIMIT_EXCEEDED', message: 'At most 100000 asset paths can be published' });
+    const added = Object.keys(manifest).filter(key => !Object.hasOwn(previous, key));
+    const changed = Object.keys(manifest).filter(key => previous[key] && (previous[key].hash !== manifest[key].hash || previous[key].size !== manifest[key].size));
+    const removed = Object.keys(previous).filter(key => !Object.hasOwn(manifest, key));
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify(manifest))));
+    const manifestHash = Array.from(digest, byte => byte.toString(16).padStart(2, '0')).join('');
+    const staticOnly = !['main', 'bindings', 'compatibility_date', 'compatibility_flags', 'assets_config'].some(key => Object.hasOwn(input, key));
+    const unchanged = staticOnly && !!currentVersion && manifestHash === currentVersion.praxis.assets_manifest?.manifest_hash;
+    const hashes = new Set(Object.values(manifest).map(entry => entry.hash));
+    const currentResult = { url: worker.subdomain.url, worker_id: worker.id, version_id: currentVersion?.id ?? null,
+        deployment_id: currentDeployment?.id ?? null, status: currentDeployment?.praxis.status ?? 'draft', created,
+        ...(currentVersion ? { version: currentVersion } : {}), unchanged, uploaded: 0, reused: hashes.size };
+    if (unchanged && !input.dryRun)
+        return currentResult;
+    // dryRun intentionally registers the content-addressed session manifest, but never uploads or publishes.
     const session = await workers.assetsUploadSession.create({ path, body: { manifest } });
+    if (input.dryRun) {
+        const missing = new Set(session.buckets.flat());
+        if ([...missing].some(hash => !hashes.has(hash)))
+            throw new PraxisError({ code: 'INVALID_RESPONSE', message: 'Upload session requested an unknown hash' });
+        return { ...currentResult, reused: hashes.size - missing.size,
+            plan: { added, changed, removed, upload_hashes: missing.size, existing_hashes: hashes.size - missing.size } };
+    }
     let jwt = session.buckets.length ? null : session.jwt;
     const uploaded = new Set();
     for (const bucket of session.buckets) {
@@ -112,5 +162,5 @@ export async function publish(client, input) {
     }
     return { url: worker.subdomain.url, worker_id: worker.id, version_id: result.version.id,
         deployment_id: deployment.id, status: deployment.praxis.status, created,
-        uploaded: uploaded.size, reused: contents.size - uploaded.size };
+        uploaded: uploaded.size, reused: hashes.size - uploaded.size };
 }

package/dist/helpers/database-count.d.ts

@@ -0,0 +1,17 @@
+import type { Transport } from '../core/transport.js';
+export interface CountInput {
+    /** Database ID from database list/create; not its display name. */
+    database_id: string;
+    /** Existing table name or ID from the database table APIs. */
+    table: string;
+    /** PostgREST query filters, as in databaseSelect; omitted means all rows. */
+    filters?: Record<string, string>;
+    /** exact counts within budget (default); filtered planned returns null; estimated may return null over budget. Unfiltered counts are exact in every mode. */
+    count?: 'exact' | 'planned' | 'estimated';
+}
+export interface CountResult {
+    /** Matching total, or null when the server reports an unknown total. */
+    count: number | null;
+}
+/** Count matching rows without retrieving row data. */
+export declare function count(transport: Pick<Transport, 'requestWithResponse'>, input: CountInput): Promise<CountResult>;

package/dist/helpers/database-count.js

@@ -0,0 +1,11 @@
+import { databaseHead } from "../generated/sdk.gen.js";
+/** Count matching rows without retrieving row data. */
+export async function count(transport, input) {
+    const { response } = await transport.requestWithResponse(databaseHead, {
+        path: { database_id: input.database_id, table: input.table },
+        query: input.filters,
+        headers: { Prefer: `count=${input.count ?? 'exact'}` },
+    });
+    const total = response.headers.get('Content-Range')?.split('/')[1];
+    return { count: total === undefined || total === '*' ? null : Number(total) };
+}

package/dist/helpers/file-upload.d.ts

@@ -0,0 +1,24 @@
+import type { Praxis } from '../core/client.js';
+import type { OwnFileOpenAiFile } from '../generated/types.gen.js';
+export interface UploadFileOptions {
+    /** user_data for conversation attachments; assistants for assistant files; vision for PNG/JPEG/GIF/WebP. */
+    purpose: 'user_data' | 'assistants' | 'vision';
+    /** Defaults to File.name, or upload for a Blob. */
+    filename?: string;
+    /** Fixed part size in bytes, 5 MiB–64 MB; defaults to 50 MiB. */
+    partSize?: number;
+    /** Concurrent part requests, a positive integer; defaults to 3. */
+    concurrency?: number;
+    /** Aborts outstanding requests and cancels an unfinished Upload. */
+    signal?: AbortSignal;
+    /** Acknowledged byte fraction, 0–1. A value of 1 does not imply processing has finished. */
+    onProgress?: (fraction: number) => void;
+}
+export type UploadedFile = OwnFileOpenAiFile;
+/** Upload a nonempty file up to 2 GiB, returning only after processing reaches active.
+ * Files up to 32 MiB use one request; larger files use fixed-size Uploads parts.
+ * Parts and complete each retry transient failures at most five times with exponential backoff.
+ * A terminal failure or abort cancels the Upload. Completed files cannot be cancelled;
+ * if abort occurs during processing, delete the resulting file explicitly if no longer needed.
+ */
+export declare function uploadFile(client: Pick<Praxis, 'file'>, file: Blob | File, options: UploadFileOptions): Promise<UploadedFile>;

package/dist/helpers/file-upload.js

@@ -0,0 +1,113 @@
+import { PraxisError, PraxisConnectionError, PraxisTimeoutError } from "../core/errors.js";
+import { sleep } from "../core/retry.js";
+const MAX_RETRIES = 5;
+function retryable(error) {
+    return error instanceof PraxisConnectionError || error instanceof PraxisTimeoutError
+        || error instanceof SyntaxError
+        || (error instanceof PraxisError && (error.status === 408 || error.status === 429 || (error.status !== undefined && error.status >= 500 && error.status <= 599)));
+}
+async function retry(signal, operation) {
+    for (let used = 0;; used++) {
+        signal.throwIfAborted();
+        try {
+            return await operation();
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            if (used >= MAX_RETRIES || !retryable(error))
+                throw error;
+            await sleep(500 * 2 ** used, signal);
+        }
+    }
+}
+/** Upload a nonempty file up to 2 GiB, returning only after processing reaches active.
+ * Files up to 32 MiB use one request; larger files use fixed-size Uploads parts.
+ * Parts and complete each retry transient failures at most five times with exponential backoff.
+ * A terminal failure or abort cancels the Upload. Completed files cannot be cancelled;
+ * if abort occurs during processing, delete the resulting file explicitly if no longer needed.
+ */
+export async function uploadFile(client, file, options) {
+    options.signal?.throwIfAborted();
+    if (file.size < 1 || file.size > 2 * 1024 ** 3)
+        throw new RangeError('File size must be 1 byte through 2 GiB');
+    const partSize = options.partSize ?? 50 * 1024 ** 2;
+    const concurrency = options.concurrency ?? 3;
+    if (!Number.isSafeInteger(partSize) || partSize < 5 * 1024 ** 2 || partSize > 64_000_000)
+        throw new RangeError('partSize must be an integer from 5242880 through 64000000');
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1)
+        throw new RangeError('concurrency must be a positive integer');
+    const filename = options.filename ?? (typeof File !== 'undefined' && file instanceof File ? file.name : 'upload');
+    const work = new AbortController();
+    const abort = () => work.abort(options.signal?.reason);
+    options.signal?.addEventListener('abort', abort, { once: true });
+    const signal = work.signal;
+    const request = { signal, maxRetries: 0, timeoutMs: 120_000 };
+    let uploadId;
+    const active = async (initial) => {
+        let result = initial;
+        for (let polls = 0;; polls++) {
+            signal.throwIfAborted();
+            if (result.state === 'active')
+                return result;
+            if (result.state !== 'processing')
+                throw new PraxisError({ code: 'FILE_PROCESSING_FAILED', message: `File ${result.id} is not active (${result.state})` });
+            await sleep(Math.min(5000, 1000 * 2 ** polls), signal);
+            result = await retry(signal, () => client.file.files.retrieve({ path: { file_id: result.id }, ...request }));
+        }
+    };
+    try {
+        signal.throwIfAborted();
+        options.onProgress?.(0);
+        if (file.size <= 32 * 1024 ** 2) {
+            const result = await client.file.files.create({ body: { file: new File([file], filename, { type: file.type }), purpose: options.purpose }, ...request });
+            options.onProgress?.(1);
+            return await active(result);
+        }
+        const upload = await client.file.uploads.create({ body: { bytes: file.size, filename, mime_type: file.type || 'application/octet-stream', purpose: options.purpose, part_size: partSize }, ...request });
+        uploadId = upload.id;
+        signal.throwIfAborted();
+        const path = { upload_id: uploadId };
+        const count = Math.ceil(file.size / partSize);
+        const ids = new Array(count);
+        let cursor = 0, confirmed = 0;
+        const worker = async () => {
+            while (cursor < count) {
+                signal.throwIfAborted();
+                const index = cursor++;
+                const chunk = file.slice(index * partSize, Math.min(file.size, (index + 1) * partSize));
+                const part = await retry(signal, () => client.file.uploads.parts.create({ path, query: { part_number: index + 1 }, body: { data: new File([chunk], filename) }, ...request }));
+                ids[index] = part.id;
+                confirmed += chunk.size;
+                options.onProgress?.(confirmed / file.size);
+            }
+        };
+        const workers = Array.from({ length: Math.min(concurrency, count) }, worker);
+        try {
+            await Promise.all(workers);
+        }
+        catch (error) {
+            work.abort();
+            await Promise.allSettled(workers);
+            throw error;
+        }
+        const result = await retry(signal, () => client.file.uploads.complete({ path, body: { part_ids: ids }, ...request }));
+        if (result.error)
+            throw new PraxisError({ code: result.error.code, message: result.error.message });
+        if (result.status !== 'completed' || !result.file)
+            throw new PraxisError({ code: 'INVALID_RESPONSE', message: 'Complete did not return a completed Upload with a file' });
+        return await active(result.file);
+    }
+    catch (error) {
+        work.abort();
+        if (uploadId) {
+            // Cleanup uses its own timeout and must not inherit the aborted work signal.
+            await client.file.uploads.cancel({ path: { upload_id: uploadId }, maxRetries: 0, timeoutMs: 10_000 }).catch(() => { });
+        }
+        if (options.signal?.aborted)
+            throw options.signal.reason;
+        throw error;
+    }
+    finally {
+        options.signal?.removeEventListener('abort', abort);
+    }
+}

package/dist/index.d.ts

@@ -7,3 +7,7 @@ export { parseSSE } from './core/sse.js';
 export type { SSEEvent, SSEOptions } from './core/sse.js';
 export { publish } from './helpers/application-publish.js';
 export type { PublishInput, PublishResult, AssetsConfig } from './helpers/application-publish.js';
+export { count } from './helpers/database-count.js';
+export type { CountInput, CountResult } from './helpers/database-count.js';
+export { uploadFile } from './helpers/file-upload.js';
+export type { UploadFileOptions, UploadedFile } from './helpers/file-upload.js';

package/dist/index.js

@@ -3,3 +3,5 @@ export { PraxisError, PraxisConnectionError, PraxisTimeoutError } from "./core/e
 export { Page } from "./core/pagination.js";
 export { parseSSE } from "./core/sse.js";
 export { publish } from "./helpers/application-publish.js";
+export { count } from "./helpers/database-count.js";
+export { uploadFile } from "./helpers/file-upload.js";