@tinycloud/share-sdk 1.1.1-beta.0 → 1.2.0-beta.0

package/dist/artifact.d.cts

@@ -0,0 +1,104 @@
+declare const ARTIFACT_ROOT = "artifacts";
+declare const ARTIFACT_MANIFEST_NAME = "manifest.json";
+declare const ARTIFACT_MANIFEST_VERSION: 1;
+/** A lost create race bumps `n`; this bounds how many times one publish retries. */
+declare const ARTIFACT_MAX_PUBLISH_ATTEMPTS = 16;
+type ArtifactErrorCode = "invalid-argument" | "conflict" | "storage" | "corrupt";
+declare class ArtifactError extends Error {
+    readonly code: ArtifactErrorCode;
+    constructor(code: ArtifactErrorCode, message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+/**
+ * The only storage operations the layout needs. `put` with `ifNoneMatch`
+ * resolves `"exists"` on a 412 and `"created"` otherwise; every other failure
+ * throws. `list` returns full keys and follows pagination to the end.
+ */
+interface ArtifactStore {
+    put(key: string, bytes: Uint8Array, options: {
+        readonly ifNoneMatch: "*";
+        readonly contentType?: string;
+    }): Promise<"created" | "exists">;
+    get(key: string): Promise<Uint8Array | undefined>;
+    list(prefix: string): Promise<readonly string[]>;
+}
+interface ArtifactManifestFile {
+    /** One safe path segment, relative to the version directory. */
+    readonly path: string;
+    /** SHA-256 (lowercase hex) of the bytes stored at this key. */
+    readonly sha256: string;
+    readonly bytes: number;
+}
+interface ArtifactManifest {
+    readonly v: typeof ARTIFACT_MANIFEST_VERSION;
+    readonly files: readonly ArtifactManifestFile[];
+    readonly createdAt: string;
+    /** The version this one follows, or `null` for the first. */
+    readonly parent: number | null;
+    readonly note?: string;
+}
+interface ArtifactVersionInput {
+    readonly artifactId: string;
+    readonly files: readonly {
+        readonly filename: string;
+        readonly bytes: Uint8Array;
+        readonly contentType?: string;
+    }[];
+    readonly note?: string;
+    readonly now?: () => number;
+}
+interface ArtifactVersionResult {
+    readonly artifactId: string;
+    readonly version: number;
+    readonly manifest: ArtifactManifest;
+    /** SHA-256 of the exact stored `manifest.json` bytes. */
+    readonly manifestSha256: string;
+    /** `false` when an existing version already held the same content (idempotent re-run). */
+    readonly created: boolean;
+}
+interface ArtifactVersionSummary {
+    readonly version: number;
+    /** `false` while `manifest.json` is missing (an interrupted or lost-race attempt) or unreadable (`corrupt`). */
+    readonly complete: boolean;
+    /** `manifest.json` exists but does not parse: the version is listed, never trusted, never reused. */
+    readonly corrupt?: true;
+    readonly manifest?: ArtifactManifest;
+    readonly manifestSha256?: string;
+}
+declare function sha256Hex(bytes: Uint8Array): string;
+declare function newArtifactId(random?: (length: number) => Uint8Array): string;
+declare function assertArtifactId(value: string): string;
+declare function artifactVersionsPrefix(artifactId: string): string;
+/** Delegation resource for one version: a prefix, NO trailing slash. */
+declare function artifactVersionResource(artifactId: string, version: number): string;
+declare function artifactVersionFilePath(artifactId: string, version: number, filename: string): string;
+/** The artifact and version a stored KV path belongs to, if it is under a version directory. */
+declare function parseArtifactVersionPath(path: string): {
+    readonly artifactId: string;
+    readonly version: number;
+    readonly file: string;
+} | undefined;
+declare function manifestBytes(manifest: ArtifactManifest): Uint8Array;
+/**
+ * Strict manifest parser. Unknown fields, duplicate paths and malformed
+ * digests are refused: the bytes a viewer verifies against are exactly the
+ * ones this accepts.
+ */
+declare function parseArtifactManifest(bytes: Uint8Array): ArtifactManifest;
+/** Versions present under `artifacts/<aid>/versions/`, ascending, with their manifests when complete. */
+declare function listArtifactVersions(store: ArtifactStore, artifactId: string): Promise<ArtifactVersionSummary[]>;
+/**
+ * Publish `files` as the next version.
+ *
+ * - Content identical to the latest complete version: no new version, that
+ *   one is returned (`created: false`). Safe to re-run after a crash.
+ * - Files are created with `If-None-Match: *`. A 412 is success only when the
+ *   stored bytes hash to the same sha256 as ours; otherwise another publisher
+ *   owns that `n` and the next number is tried.
+ * - `manifest.json` is written last. A version without one is incomplete and
+ *   is never reused, and a manifest lists the only files it vouches for.
+ */
+declare function publishArtifactVersion(store: ArtifactStore, input: ArtifactVersionInput): Promise<ArtifactVersionResult>;
+
+export { ARTIFACT_MANIFEST_NAME, ARTIFACT_MANIFEST_VERSION, ARTIFACT_MAX_PUBLISH_ATTEMPTS, ARTIFACT_ROOT, ArtifactError, type ArtifactErrorCode, type ArtifactManifest, type ArtifactManifestFile, type ArtifactStore, type ArtifactVersionInput, type ArtifactVersionResult, type ArtifactVersionSummary, artifactVersionFilePath, artifactVersionResource, artifactVersionsPrefix, assertArtifactId, listArtifactVersions, manifestBytes, newArtifactId, parseArtifactManifest, parseArtifactVersionPath, publishArtifactVersion, sha256Hex };

package/dist/artifact.d.ts

@@ -0,0 +1,104 @@
+declare const ARTIFACT_ROOT = "artifacts";
+declare const ARTIFACT_MANIFEST_NAME = "manifest.json";
+declare const ARTIFACT_MANIFEST_VERSION: 1;
+/** A lost create race bumps `n`; this bounds how many times one publish retries. */
+declare const ARTIFACT_MAX_PUBLISH_ATTEMPTS = 16;
+type ArtifactErrorCode = "invalid-argument" | "conflict" | "storage" | "corrupt";
+declare class ArtifactError extends Error {
+    readonly code: ArtifactErrorCode;
+    constructor(code: ArtifactErrorCode, message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+/**
+ * The only storage operations the layout needs. `put` with `ifNoneMatch`
+ * resolves `"exists"` on a 412 and `"created"` otherwise; every other failure
+ * throws. `list` returns full keys and follows pagination to the end.
+ */
+interface ArtifactStore {
+    put(key: string, bytes: Uint8Array, options: {
+        readonly ifNoneMatch: "*";
+        readonly contentType?: string;
+    }): Promise<"created" | "exists">;
+    get(key: string): Promise<Uint8Array | undefined>;
+    list(prefix: string): Promise<readonly string[]>;
+}
+interface ArtifactManifestFile {
+    /** One safe path segment, relative to the version directory. */
+    readonly path: string;
+    /** SHA-256 (lowercase hex) of the bytes stored at this key. */
+    readonly sha256: string;
+    readonly bytes: number;
+}
+interface ArtifactManifest {
+    readonly v: typeof ARTIFACT_MANIFEST_VERSION;
+    readonly files: readonly ArtifactManifestFile[];
+    readonly createdAt: string;
+    /** The version this one follows, or `null` for the first. */
+    readonly parent: number | null;
+    readonly note?: string;
+}
+interface ArtifactVersionInput {
+    readonly artifactId: string;
+    readonly files: readonly {
+        readonly filename: string;
+        readonly bytes: Uint8Array;
+        readonly contentType?: string;
+    }[];
+    readonly note?: string;
+    readonly now?: () => number;
+}
+interface ArtifactVersionResult {
+    readonly artifactId: string;
+    readonly version: number;
+    readonly manifest: ArtifactManifest;
+    /** SHA-256 of the exact stored `manifest.json` bytes. */
+    readonly manifestSha256: string;
+    /** `false` when an existing version already held the same content (idempotent re-run). */
+    readonly created: boolean;
+}
+interface ArtifactVersionSummary {
+    readonly version: number;
+    /** `false` while `manifest.json` is missing (an interrupted or lost-race attempt) or unreadable (`corrupt`). */
+    readonly complete: boolean;
+    /** `manifest.json` exists but does not parse: the version is listed, never trusted, never reused. */
+    readonly corrupt?: true;
+    readonly manifest?: ArtifactManifest;
+    readonly manifestSha256?: string;
+}
+declare function sha256Hex(bytes: Uint8Array): string;
+declare function newArtifactId(random?: (length: number) => Uint8Array): string;
+declare function assertArtifactId(value: string): string;
+declare function artifactVersionsPrefix(artifactId: string): string;
+/** Delegation resource for one version: a prefix, NO trailing slash. */
+declare function artifactVersionResource(artifactId: string, version: number): string;
+declare function artifactVersionFilePath(artifactId: string, version: number, filename: string): string;
+/** The artifact and version a stored KV path belongs to, if it is under a version directory. */
+declare function parseArtifactVersionPath(path: string): {
+    readonly artifactId: string;
+    readonly version: number;
+    readonly file: string;
+} | undefined;
+declare function manifestBytes(manifest: ArtifactManifest): Uint8Array;
+/**
+ * Strict manifest parser. Unknown fields, duplicate paths and malformed
+ * digests are refused: the bytes a viewer verifies against are exactly the
+ * ones this accepts.
+ */
+declare function parseArtifactManifest(bytes: Uint8Array): ArtifactManifest;
+/** Versions present under `artifacts/<aid>/versions/`, ascending, with their manifests when complete. */
+declare function listArtifactVersions(store: ArtifactStore, artifactId: string): Promise<ArtifactVersionSummary[]>;
+/**
+ * Publish `files` as the next version.
+ *
+ * - Content identical to the latest complete version: no new version, that
+ *   one is returned (`created: false`). Safe to re-run after a crash.
+ * - Files are created with `If-None-Match: *`. A 412 is success only when the
+ *   stored bytes hash to the same sha256 as ours; otherwise another publisher
+ *   owns that `n` and the next number is tried.
+ * - `manifest.json` is written last. A version without one is incomplete and
+ *   is never reused, and a manifest lists the only files it vouches for.
+ */
+declare function publishArtifactVersion(store: ArtifactStore, input: ArtifactVersionInput): Promise<ArtifactVersionResult>;
+
+export { ARTIFACT_MANIFEST_NAME, ARTIFACT_MANIFEST_VERSION, ARTIFACT_MAX_PUBLISH_ATTEMPTS, ARTIFACT_ROOT, ArtifactError, type ArtifactErrorCode, type ArtifactManifest, type ArtifactManifestFile, type ArtifactStore, type ArtifactVersionInput, type ArtifactVersionResult, type ArtifactVersionSummary, artifactVersionFilePath, artifactVersionResource, artifactVersionsPrefix, assertArtifactId, listArtifactVersions, manifestBytes, newArtifactId, parseArtifactManifest, parseArtifactVersionPath, publishArtifactVersion, sha256Hex };