@deepraxis/sdk 0.0.0-stage → 0.1.0-dev.086e3bf

package/dist/generated/types.gen.js

@@ -0,0 +1,2 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export {};

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

@@ -0,0 +1,61 @@
+import type { Praxis } from '../core/client.js';
+import type { ApplicationAssetsConfig, ApplicationBinding, ApplicationVersion } from '../generated/types.gen.js';
+export type AssetsConfig = ApplicationAssetsConfig;
+export interface PublishInput {
+    /** 应用名；存在同名应用时复用。 */
+    name: string;
+    /** 站点路径到 UTF-8 文本或字节内容；自动补前导 /。 */
+    files: Record<string, string | Uint8Array>;
+    /** 可选 Worker 入口脚本；省略时发布纯静态站点。 */
+    main?: {
+        name: string;
+        content: string;
+        content_type?: string;
+    };
+    /** 运行时兼容日期，默认当天 UTC（YYYY-MM-DD）。 */
+    compatibility_date?: string;
+    /** 运行时兼容标志，原样传递；平台固定附加 global_fetch_strictly_public。 */
+    compatibility_flags?: string[];
+    /** 绑定声明（d1、kv_namespace、r2_bucket、secret_text、plain_text、json 等），原样传递。 */
+    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 | null;
+    deployment_id: string | null;
+    status: string;
+    created: boolean;
+    /** 本次上传的不同内容 hash 数量。 */
+    uploaded: number;
+    /** 服务端已存在的不同内容 hash 数量。 */
+    reused: number;
+}
+/** 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

@@ -0,0 +1,166 @@
+import { PraxisError } from "../core/errors.js";
+// Application contract: 100k paths, 25 MiB/file; session buckets: 50 files / 40 MiB.
+const FILE_BYTES = 25 * 1024 * 1024;
+function base64(bytes) {
+    const chunks = [];
+    for (let offset = 0; offset < bytes.length; offset += 8192) {
+        chunks.push(String.fromCharCode(...bytes.subarray(offset, offset + 8192)));
+    }
+    return btoa(chunks.join(''));
+}
+/** 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');
+    const contentType = ['application/javascript+module', 'text/javascript', 'application/javascript', 'application/json',
+        'text/plain', 'application/wasm', 'application/octet-stream', 'application/x-python']
+        .find(type => type === (input.main?.content_type ?? 'application/javascript+module'));
+    if (!contentType)
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: `Unsupported module content_type: ${input.main?.content_type}` });
+    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' });
+    let manifest = {};
+    const contents = new Map();
+    for (const [path, content] of files) {
+        const normalized = path.startsWith('/') ? path : `/${path}`;
+        if (Object.hasOwn(manifest, normalized))
+            throw new PraxisError({ code: 'INVALID_PARAMS', message: `Duplicate asset path: ${normalized}` });
+        const bytes = typeof content === 'string' ? new TextEncoder().encode(content) : new Uint8Array(content);
+        if (bytes.length > FILE_BYTES)
+            throw new PraxisError({ code: 'LIMIT_EXCEEDED', message: `Asset ${normalized} exceeds 25 MiB` });
+        const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', bytes));
+        const hash = Array.from(digest.subarray(0, 16), byte => byte.toString(16).padStart(2, '0')).join('');
+        manifest[normalized] = { hash, size: bytes.length };
+        contents.set(hash, bytes);
+    }
+    const { workers, assets } = client.application;
+    let worker;
+    for await (const candidate of await workers.list()) {
+        if (candidate.name === input.name) {
+            worker = candidate;
+            break;
+        }
+    }
+    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) {
+        const batch = {};
+        let size = 0;
+        for (const hash of bucket) {
+            const bytes = contents.get(hash);
+            if (!bytes)
+                throw new PraxisError({ code: 'INVALID_RESPONSE', message: `Upload session requested unknown hash ${hash}` });
+            size += bytes.length;
+            batch[hash] = base64(bytes);
+        }
+        if (bucket.length > 50 || size > 40 * 1024 * 1024)
+            throw new PraxisError({ code: 'INVALID_RESPONSE', message: 'Upload session bucket exceeds 50 files or 40 MiB' });
+        const result = await assets.upload.create({ body: { jwt: session.jwt, files: batch } });
+        jwt = result.jwt;
+        for (const hash of bucket)
+            uploaded.add(hash);
+    }
+    if (!jwt)
+        throw new PraxisError({ code: 'INVALID_RESPONSE', message: 'Asset upload did not return a completion JWT' });
+    // The service contract accepts jwt instead of manifest. Its generated OpenAPI
+    // type currently omits jwt; keep this explicit shape until that schema catches up.
+    const versionAssets = { jwt, ...(input.assets_config ? { config: input.assets_config } : {}) };
+    const result = await workers.versions.create({ path, body: {
+            deploy: true,
+            compatibility_date: input.compatibility_date ?? new Date().toISOString().slice(0, 10),
+            assets: versionAssets,
+            ...(input.compatibility_flags ? { compatibility_flags: input.compatibility_flags } : {}),
+            ...(input.bindings ? { bindings: input.bindings } : {}),
+            ...(input.main ? { main_module: input.main.name, modules: [{ name: input.main.name,
+                        content_type: contentType,
+                        content_base64: base64(new TextEncoder().encode(input.main.content)) }] } : {}),
+        } });
+    let deployment = result.deployment;
+    if (!deployment)
+        throw new PraxisError({ code: 'INVALID_RESPONSE', message: 'Version creation did not return a deployment' });
+    if (input.wait ?? true) {
+        const deadline = Date.now() + timeout;
+        const timedOut = () => new PraxisError({ code: 'DEPLOY_TIMEOUT', message: `Deployment ${deployment.id} did not become active within ${timeout} ms; deployment may still be running` });
+        let interval = 500;
+        while (deployment.praxis.status !== 'active') {
+            if (deployment.praxis.status === 'failed') {
+                const error = deployment.praxis.error;
+                throw new PraxisError({ code: error?.code ?? 'DEPLOYMENT_FAILED', message: error?.message ?? `Deployment ${deployment.id} failed`, raw: error });
+            }
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                throw timedOut();
+            await new Promise(resolve => setTimeout(resolve, Math.min(interval, remaining)));
+            if (Date.now() >= deadline)
+                throw timedOut();
+            try {
+                deployment = await workers.deployments.retrieve({ path: { ...path, deployment_id: deployment.id }, timeoutMs: deadline - Date.now() });
+            }
+            catch (error) {
+                if (error instanceof PraxisError && error.code === 'TIMEOUT')
+                    throw timedOut();
+                throw error;
+            }
+            interval = Math.min(interval * 2, 2000);
+        }
+    }
+    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: hashes.size - uploaded.size };
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { Praxis } from './core/client.js';
+export type { PraxisOptions, RequestOptions } from './core/client.js';
+export { PraxisError, PraxisConnectionError, PraxisTimeoutError } from './core/errors.js';
+export type { ProblemDetails } from './core/errors.js';
+export { Page } from './core/pagination.js';
+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';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { Praxis } from "./core/client.js";
+export { PraxisError, PraxisConnectionError, PraxisTimeoutError } from "./core/errors.js";
+export { Page } from "./core/pagination.js";
+export { parseSSE } from "./core/sse.js";
+export { publish } from "./helpers/application-publish.js";