@jsm-mit/sultana-assets-rust-package 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# @jsm-mit/sultana-assets-rust-package
+
+TypeScript wrapper for the [`sultana-assets-rust`](../sultana-assets-rust) canister — Sultana's
+asset storage on the Internet Computer (salon images, videos, music tracks, posters) — plus
+the integration tests that prove it.
+
+```ts
+import { AssetsRustSalonActor, AssetsRustUploadsActor, AssetsRustAssetsActor } from "@jsm-mit/sultana-assets-rust-package";
+
+// A salon owner puts an image into the salon's library. The canister asks
+// sultana-core-motoko first (owner? quota?), makes a thumbnail, stores both and registers
+// them in core — or traps and stores nothing.
+const salon = new AssetsRustSalonActor(assetsCanisterId, ownerIdentity);
+const imageId = await salon.uploadImageAsyncUnsafe({ salonId, name: "front.jpg", contentType: "image/jpeg", data });
+
+// A video goes to a transcoding worker, not to the canister: reserve an id, then upload to
+// one of the returned worker URLs (sultana-core-motoko-package's VideoUploadClient does it).
+const { id, uploadUrls } = await salon.reserveTranscodingUploadAsyncUnsafe({ salonId, name: "promo" });
+
+// Any file, any size, not tied to a salon: a chunked session.
+const fileId = await new AssetsRustUploadsActor(assetsCanisterId, identity).uploadBytesAsyncUnsafe("notes.pdf", "application/pdf", bytes);
+
+// Reads are anonymous.
+const assets = new AssetsRustAssetsActor(assetsCanisterId);
+const info = await assets.getAssetInfoAsyncUnsafe(imageId);
+const url = assets.assetUrl(imageId); // https://<canister>.raw.icp0.io/asset/<id>
+```
+
+One class per part of the canister:
+
+| Class | Calls | Who |
+|---|---|---|
+| `AssetsRustAdminActor` | core link (claim-once), worker list, `delete_asset`, the reservation sweep | the core canister (via core's superadmin proxies); wiring scripts |
+| `AssetsRustUploadsActor` | chunked session, single-shot upload, `uploadBytesAsyncUnsafe` | any signed-in caller |
+| `AssetsRustSalonActor` | `upload_image`, `delete_salon_asset`, transcoding and render reservations | the salon's owner — core decides |
+| `AssetsRustWorkerActor` | system upload of a transcoded result under a reserved id | listed transcoding workers |
+| `AssetsRustAssetsActor` | `get_asset_info`, `list_assets`, `http_request`, `assetUrl` | anybody |
+
+Every method is `…AsyncUnsafe` and throws one of three errors, like the other wrapper
+packages:
+
+- `CanisterError` — the canister trapped. sultana-assets-rust has no error variants: it
+  returns the value or traps, so `cause` is `{ errorKey: "Trap", errorMessage: <trap text>,
+  rawError }` — e.g. `"upload not authorized: core canUploadAsset rejected: …"`.
+- `CallRefusedAtInspectionStage` — refused before execution (kept for the shared vocabulary;
+  the canister has no `inspect_message` today).
+- `CriticalCanisterError` — anything else: transport, an unreachable canister, no cycles.
+
+Methods the canister answers with `false` for a refusal (`setCoreCanister`, `setWorkers`,
+`deleteAsset`, `abortUpload`, `failSystemUpload`) return that boolean. Views turn
+`Principal` into text, `opt` into optional fields, variants into string unions and sizes
+into `number`; timestamps stay `bigint` nanoseconds. `ASSETS_RUST_LIMITS` carries the
+canister's limits (chunk size, render settings) for checks before a call. The raw candid
+types are exported too, and `./declarations/*` gives the generated files.
+
+`src/` is browser-safe — the same package serves the biz panel, the playground and the
+transcoding worker.
+
+Scripts: `build`, `typecheck`, `sync-declarations`, `test-suite`, `redeploy`, `sandbox`
+(an interactive console: `npm run sandbox -- <canister-id>`, caller from `IDENTITY_PEM` in
+`.env` or anonymous), `stamp-canister`, `publish-public`. See `CLAUDE.md` for who runs what.
+
+## Integration tests
+
+`npm run test-suite` reinstalls the current `../sultana-assets-rust` build into the crafting
+table's `short-living` slot (lease 3 minutes) and runs `tests/test-suite.ts` there. No
+`.env`, no PEMs: every identity is generated per run. A fresh canister has no core canister,
+so the suite claims that claim-once seat for a generated identity and plays core itself.
+
+What the suite covers: the core seat and the worker list; chunked and single-shot uploads
+with every owner and size check; reads, HTTP 200/206/404, certification header and
+streaming; the worker's system upload with a poster; `delete_asset` taking the thumb along;
+the `reserve_render` input checks. What it leaves to `sultana-command-line-playground`: every
+path where core says yes — the canister's calls out to core go to the generated identity and
+fail, and the suite asserts exactly that trap. Rabbit is reached only after core agreed, so
+the suite never touches it.
+
+## Publishing
+
+Bump the version by hand, commit, push, then `npm run publish-public`. It refuses unless this
+repo and `../sultana-assets-rust` are on a clean, pushed `master` and the version is new on
+npm; it reinstalls the canister's master into `short-living` (lease 1), checks that its
+`candid:service` equals `declarations/sultana-assets-rust/sultana-assets-rust.did` as dfx
+rewrites it (the hand-written .did is normalized by a local `dfx build --check` first), stamps
+`sultanaAssets.{repo, repoUrl, commit}` into package.json, publishes and commits `Version bump
+to <version>`.

package/declarations/sultana-assets-rust/sultana-assets-rust.did

@@ -0,0 +1,98 @@
+type AssetInfo = record {
+  id : text;
+  contentType : text;
+  name : text;
+  uploadedAt : int64;
+  totalSize : nat64;
+  chunkCount : nat32;
+};
+type StreamingCallbackToken = record {
+  key : text;
+  index : nat32;
+  contentEncoding : text;
+  sha256 : opt blob;
+};
+type StreamingCallbackHttpResponse = record {
+  body : blob;
+  token : opt StreamingCallbackToken;
+};
+type StreamingStrategy = variant {
+  Callback : record {
+    callback : func (StreamingCallbackToken) -> (StreamingCallbackHttpResponse) query;
+    token : StreamingCallbackToken;
+  };
+};
+type HttpRequest = record {
+  url : text;
+  method : text;
+  body : blob;
+  headers : vec record { text; text };
+};
+type HttpResponse = record {
+  body : blob;
+  headers : vec record { text; text };
+  streaming_strategy : opt StreamingStrategy;
+  upgrade : opt bool;
+  status_code : nat16;
+};
+type UploadArgs = record { contentType : text; data : blob; name : text };
+type WorkerEntry = record { "principal" : principal; url : text };
+type ReserveTranscodingUpload = record { id : text; uploadUrls : vec text };
+type StartUploadArgs = record {
+  contentType : text;
+  name : text;
+  totalChunks : nat32;
+};
+type SystemStartUploadArgs = record {
+  id : text;
+  contentType : text;
+  name : text;
+  totalChunks : nat32;
+};
+type FinishSystemUploadArgs = record { id : text; posterId : opt text };
+type FailSystemUploadArgs = record { id : text; reason : text };
+type UploadImageArgs = record {
+  contentType : text;
+  data : blob;
+  name : text;
+  salonId : text;
+  targetSalonServiceId : opt text;
+};
+type DeleteSalonAssetArgs = record { id : text; salonId : text };
+type TranscodingKind = variant { Video; Audio };
+type ReserveTranscodingUploadArgs = record { salonId : text; kind : opt TranscodingKind; name : opt text };
+type RenderMode = variant { Replace; Mix };
+type ReserveRenderArgs = record {
+  salonId : text;
+  sourceAssetId : text;
+  audioAssetId : text;
+  mode : RenderMode;
+  musicVolumePct : nat8;
+  musicStartSec : opt nat32;
+  slideDurationSec : opt nat16;
+  name : opt text;
+};
+service : () -> {
+  abort_upload : (text) -> (bool);
+  delete_asset : (text) -> (bool);
+  delete_salon_asset : (DeleteSalonAssetArgs) -> (bool);
+  fail_system_upload : (FailSystemUploadArgs) -> (bool);
+  finish_system_upload : (FinishSystemUploadArgs) -> (text);
+  finish_upload : (text) -> (text);
+  get_asset_info : (text) -> (opt AssetInfo) query;
+  get_core_canister : () -> (opt principal) query;
+  get_workers : () -> (vec WorkerEntry) query;
+  http_request : (HttpRequest) -> (HttpResponse) query;
+  http_request_streaming_callback : (StreamingCallbackToken) -> (StreamingCallbackHttpResponse) query;
+  list_assets : () -> (vec AssetInfo) query;
+  reserve_render : (ReserveRenderArgs) -> (ReserveTranscodingUpload);
+  reserve_transcoding_upload : (ReserveTranscodingUploadArgs) -> (ReserveTranscodingUpload);
+  run_reservation_sweep : (nat64) -> (nat32);
+  set_core_canister : (principal) -> (bool);
+  set_workers : (vec WorkerEntry) -> (bool);
+  start_upload : (StartUploadArgs) -> (text);
+  system_start_upload : (SystemStartUploadArgs) -> (text);
+  upload_asset : (UploadArgs) -> (text);
+  upload_chunk : (text, nat32, blob) -> ();
+  upload_image : (UploadImageArgs) -> (text);
+}

package/declarations/sultana-assets-rust/sultana-assets-rust.did.d.ts

@@ -0,0 +1,129 @@
+import type { Principal } from '@icp-sdk/core/principal';
+import type { ActorMethod } from '@icp-sdk/core/agent';
+import type { IDL } from '@icp-sdk/core/candid';
+
+export interface AssetInfo {
+  'id' : string,
+  'contentType' : string,
+  'name' : string,
+  'totalSize' : bigint,
+  'chunkCount' : number,
+  'uploadedAt' : bigint,
+}
+export interface DeleteSalonAssetArgs { 'id' : string, 'salonId' : string }
+export interface FailSystemUploadArgs { 'id' : string, 'reason' : string }
+export interface FinishSystemUploadArgs {
+  'id' : string,
+  'posterId' : [] | [string],
+}
+export interface HttpRequest {
+  'url' : string,
+  'method' : string,
+  'body' : Uint8Array | number[],
+  'headers' : Array<[string, string]>,
+}
+export interface HttpResponse {
+  'body' : Uint8Array | number[],
+  'headers' : Array<[string, string]>,
+  'upgrade' : [] | [boolean],
+  'streaming_strategy' : [] | [StreamingStrategy],
+  'status_code' : number,
+}
+export type RenderMode = { 'Mix' : null } |
+  { 'Replace' : null };
+export interface ReserveRenderArgs {
+  'slideDurationSec' : [] | [number],
+  'musicStartSec' : [] | [number],
+  'audioAssetId' : string,
+  'mode' : RenderMode,
+  'name' : [] | [string],
+  'sourceAssetId' : string,
+  'musicVolumePct' : number,
+  'salonId' : string,
+}
+export interface ReserveTranscodingUpload {
+  'id' : string,
+  'uploadUrls' : Array<string>,
+}
+export interface ReserveTranscodingUploadArgs {
+  'kind' : [] | [TranscodingKind],
+  'name' : [] | [string],
+  'salonId' : string,
+}
+export interface StartUploadArgs {
+  'contentType' : string,
+  'name' : string,
+  'totalChunks' : number,
+}
+export interface StreamingCallbackHttpResponse {
+  'token' : [] | [StreamingCallbackToken],
+  'body' : Uint8Array | number[],
+}
+export interface StreamingCallbackToken {
+  'key' : string,
+  'sha256' : [] | [Uint8Array | number[]],
+  'index' : number,
+  'contentEncoding' : string,
+}
+export type StreamingStrategy = {
+    'Callback' : {
+      'token' : StreamingCallbackToken,
+      'callback' : [Principal, string],
+    }
+  };
+export interface SystemStartUploadArgs {
+  'id' : string,
+  'contentType' : string,
+  'name' : string,
+  'totalChunks' : number,
+}
+export type TranscodingKind = { 'Audio' : null } |
+  { 'Video' : null };
+export interface UploadArgs {
+  'contentType' : string,
+  'data' : Uint8Array | number[],
+  'name' : string,
+}
+export interface UploadImageArgs {
+  'contentType' : string,
+  'data' : Uint8Array | number[],
+  'name' : string,
+  'targetSalonServiceId' : [] | [string],
+  'salonId' : string,
+}
+export interface WorkerEntry { 'url' : string, 'principal' : Principal }
+export interface _SERVICE {
+  'abort_upload' : ActorMethod<[string], boolean>,
+  'delete_asset' : ActorMethod<[string], boolean>,
+  'delete_salon_asset' : ActorMethod<[DeleteSalonAssetArgs], boolean>,
+  'fail_system_upload' : ActorMethod<[FailSystemUploadArgs], boolean>,
+  'finish_system_upload' : ActorMethod<[FinishSystemUploadArgs], string>,
+  'finish_upload' : ActorMethod<[string], string>,
+  'get_asset_info' : ActorMethod<[string], [] | [AssetInfo]>,
+  'get_core_canister' : ActorMethod<[], [] | [Principal]>,
+  'get_workers' : ActorMethod<[], Array<WorkerEntry>>,
+  'http_request' : ActorMethod<[HttpRequest], HttpResponse>,
+  'http_request_streaming_callback' : ActorMethod<
+    [StreamingCallbackToken],
+    StreamingCallbackHttpResponse
+  >,
+  'list_assets' : ActorMethod<[], Array<AssetInfo>>,
+  'reserve_render' : ActorMethod<[ReserveRenderArgs], ReserveTranscodingUpload>,
+  'reserve_transcoding_upload' : ActorMethod<
+    [ReserveTranscodingUploadArgs],
+    ReserveTranscodingUpload
+  >,
+  'run_reservation_sweep' : ActorMethod<[bigint], number>,
+  'set_core_canister' : ActorMethod<[Principal], boolean>,
+  'set_workers' : ActorMethod<[Array<WorkerEntry>], boolean>,
+  'start_upload' : ActorMethod<[StartUploadArgs], string>,
+  'system_start_upload' : ActorMethod<[SystemStartUploadArgs], string>,
+  'upload_asset' : ActorMethod<[UploadArgs], string>,
+  'upload_chunk' : ActorMethod<
+    [string, number, Uint8Array | number[]],
+    undefined
+  >,
+  'upload_image' : ActorMethod<[UploadImageArgs], string>,
+}
+export declare const idlFactory: IDL.InterfaceFactory;
+export declare const init: (args: { IDL: typeof IDL }) => IDL.Type[];

package/declarations/sultana-assets-rust/sultana-assets-rust.did.js

@@ -0,0 +1,143 @@
+export const idlFactory = ({ IDL }) => {
+  const DeleteSalonAssetArgs = IDL.Record({
+    'id' : IDL.Text,
+    'salonId' : IDL.Text,
+  });
+  const FailSystemUploadArgs = IDL.Record({
+    'id' : IDL.Text,
+    'reason' : IDL.Text,
+  });
+  const FinishSystemUploadArgs = IDL.Record({
+    'id' : IDL.Text,
+    'posterId' : IDL.Opt(IDL.Text),
+  });
+  const AssetInfo = IDL.Record({
+    'id' : IDL.Text,
+    'contentType' : IDL.Text,
+    'name' : IDL.Text,
+    'totalSize' : IDL.Nat64,
+    'chunkCount' : IDL.Nat32,
+    'uploadedAt' : IDL.Int64,
+  });
+  const WorkerEntry = IDL.Record({
+    'url' : IDL.Text,
+    'principal' : IDL.Principal,
+  });
+  const HttpRequest = IDL.Record({
+    'url' : IDL.Text,
+    'method' : IDL.Text,
+    'body' : IDL.Vec(IDL.Nat8),
+    'headers' : IDL.Vec(IDL.Tuple(IDL.Text, IDL.Text)),
+  });
+  const StreamingCallbackToken = IDL.Record({
+    'key' : IDL.Text,
+    'sha256' : IDL.Opt(IDL.Vec(IDL.Nat8)),
+    'index' : IDL.Nat32,
+    'contentEncoding' : IDL.Text,
+  });
+  const StreamingCallbackHttpResponse = IDL.Record({
+    'token' : IDL.Opt(StreamingCallbackToken),
+    'body' : IDL.Vec(IDL.Nat8),
+  });
+  const StreamingStrategy = IDL.Variant({
+    'Callback' : IDL.Record({
+      'token' : StreamingCallbackToken,
+      'callback' : IDL.Func(
+          [StreamingCallbackToken],
+          [StreamingCallbackHttpResponse],
+          ['query'],
+        ),
+    }),
+  });
+  const HttpResponse = IDL.Record({
+    'body' : IDL.Vec(IDL.Nat8),
+    'headers' : IDL.Vec(IDL.Tuple(IDL.Text, IDL.Text)),
+    'upgrade' : IDL.Opt(IDL.Bool),
+    'streaming_strategy' : IDL.Opt(StreamingStrategy),
+    'status_code' : IDL.Nat16,
+  });
+  const RenderMode = IDL.Variant({ 'Mix' : IDL.Null, 'Replace' : IDL.Null });
+  const ReserveRenderArgs = IDL.Record({
+    'slideDurationSec' : IDL.Opt(IDL.Nat16),
+    'musicStartSec' : IDL.Opt(IDL.Nat32),
+    'audioAssetId' : IDL.Text,
+    'mode' : RenderMode,
+    'name' : IDL.Opt(IDL.Text),
+    'sourceAssetId' : IDL.Text,
+    'musicVolumePct' : IDL.Nat8,
+    'salonId' : IDL.Text,
+  });
+  const ReserveTranscodingUpload = IDL.Record({
+    'id' : IDL.Text,
+    'uploadUrls' : IDL.Vec(IDL.Text),
+  });
+  const TranscodingKind = IDL.Variant({
+    'Audio' : IDL.Null,
+    'Video' : IDL.Null,
+  });
+  const ReserveTranscodingUploadArgs = IDL.Record({
+    'kind' : IDL.Opt(TranscodingKind),
+    'name' : IDL.Opt(IDL.Text),
+    'salonId' : IDL.Text,
+  });
+  const StartUploadArgs = IDL.Record({
+    'contentType' : IDL.Text,
+    'name' : IDL.Text,
+    'totalChunks' : IDL.Nat32,
+  });
+  const SystemStartUploadArgs = IDL.Record({
+    'id' : IDL.Text,
+    'contentType' : IDL.Text,
+    'name' : IDL.Text,
+    'totalChunks' : IDL.Nat32,
+  });
+  const UploadArgs = IDL.Record({
+    'contentType' : IDL.Text,
+    'data' : IDL.Vec(IDL.Nat8),
+    'name' : IDL.Text,
+  });
+  const UploadImageArgs = IDL.Record({
+    'contentType' : IDL.Text,
+    'data' : IDL.Vec(IDL.Nat8),
+    'name' : IDL.Text,
+    'targetSalonServiceId' : IDL.Opt(IDL.Text),
+    'salonId' : IDL.Text,
+  });
+  return IDL.Service({
+    'abort_upload' : IDL.Func([IDL.Text], [IDL.Bool], []),
+    'delete_asset' : IDL.Func([IDL.Text], [IDL.Bool], []),
+    'delete_salon_asset' : IDL.Func([DeleteSalonAssetArgs], [IDL.Bool], []),
+    'fail_system_upload' : IDL.Func([FailSystemUploadArgs], [IDL.Bool], []),
+    'finish_system_upload' : IDL.Func([FinishSystemUploadArgs], [IDL.Text], []),
+    'finish_upload' : IDL.Func([IDL.Text], [IDL.Text], []),
+    'get_asset_info' : IDL.Func([IDL.Text], [IDL.Opt(AssetInfo)], ['query']),
+    'get_core_canister' : IDL.Func([], [IDL.Opt(IDL.Principal)], ['query']),
+    'get_workers' : IDL.Func([], [IDL.Vec(WorkerEntry)], ['query']),
+    'http_request' : IDL.Func([HttpRequest], [HttpResponse], ['query']),
+    'http_request_streaming_callback' : IDL.Func(
+        [StreamingCallbackToken],
+        [StreamingCallbackHttpResponse],
+        ['query'],
+      ),
+    'list_assets' : IDL.Func([], [IDL.Vec(AssetInfo)], ['query']),
+    'reserve_render' : IDL.Func(
+        [ReserveRenderArgs],
+        [ReserveTranscodingUpload],
+        [],
+      ),
+    'reserve_transcoding_upload' : IDL.Func(
+        [ReserveTranscodingUploadArgs],
+        [ReserveTranscodingUpload],
+        [],
+      ),
+    'run_reservation_sweep' : IDL.Func([IDL.Nat64], [IDL.Nat32], []),
+    'set_core_canister' : IDL.Func([IDL.Principal], [IDL.Bool], []),
+    'set_workers' : IDL.Func([IDL.Vec(WorkerEntry)], [IDL.Bool], []),
+    'start_upload' : IDL.Func([StartUploadArgs], [IDL.Text], []),
+    'system_start_upload' : IDL.Func([SystemStartUploadArgs], [IDL.Text], []),
+    'upload_asset' : IDL.Func([UploadArgs], [IDL.Text], []),
+    'upload_chunk' : IDL.Func([IDL.Text, IDL.Nat32, IDL.Vec(IDL.Nat8)], [], []),
+    'upload_image' : IDL.Func([UploadImageArgs], [IDL.Text], []),
+  });
+};
+export const init = ({ IDL }) => { return []; };

package/dist/actor-base.d.ts

@@ -0,0 +1,46 @@
+import { type ActorSubclass, HttpAgent, type Identity } from "@icp-sdk/core/agent";
+import type { _SERVICE } from "../declarations/sultana-assets-rust/sultana-assets-rust.did.js";
+/** The `cause` of a `CanisterError` thrown by this package — the canister trapped. */
+export interface TrapCause {
+    /** Always "Trap": sultana-assets-rust has no error variants, every refusal is a trap. */
+    errorKey: "Trap";
+    /** The text the canister trapped with, e.g. "caller is not the upload owner". */
+    errorMessage: string;
+    /** The agent's error, untouched. */
+    rawError: unknown;
+}
+/**
+ * Base class for every per-domain actor wrapper (AssetsRustUploadsActor, …). Builds the
+ * HttpAgent + raw candid actor and owns the single choke point that turns the agent's
+ * failures into the three errors every wrapper package throws:
+ * - a trap is thrown as `Error("CanisterError", { cause: {errorKey: "Trap", errorMessage, rawError} })`
+ *   — sultana-assets-rust returns no Framework.Result, it returns the value or traps;
+ * - an inspect-stage rejection is thrown as `Error("CallRefusedAtInspectionStage")`;
+ * - any other failure (unreachable canister, out of cycles, bad reply) is thrown as
+ *   `Error("CriticalCanisterError", { cause: {logs: null, rawError} })`.
+ */
+export declare class ActorBase {
+    protected canisterId: string;
+    protected identity?: Identity | undefined;
+    protected host: string;
+    protected actor: ActorSubclass<_SERVICE>;
+    protected agent: HttpAgent;
+    /**
+     * @param canisterId - The sultana-assets-rust canister to talk to.
+     * @param identity - The caller; left out = anonymous (enough for the reads).
+     * @param host - The IC API host; default https://icp0.io.
+     */
+    constructor(canisterId: string, identity?: Identity | undefined, host?: string);
+    private initAgentAndActor;
+    /**
+     * Rebuilds the HttpAgent and the actor from scratch — for long-lived consumers after a
+     * streak of failed calls, where a stale agent/connection is the usual suspect. Safe to
+     * call at any time.
+     */
+    reinitializeAgent(): void;
+    /** Runs one canister call and translates its failure (see the class comment). */
+    protected executeFunctionAsyncUnsafe<T>(fnAsync: () => Promise<T>): Promise<T>;
+    protected isInspectionRejection(error: any): boolean;
+    protected extractTrapMessage(error: any): string | null;
+}
+//# sourceMappingURL=actor-base.d.ts.map

package/dist/actor-base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-base.d.ts","sourceRoot":"","sources":["../src/actor-base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAS,MAAM,qBAAqB,CAAC;AAE1F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gEAAgE,CAAC;AAG/F,sFAAsF;AACtF,MAAM,WAAW,SAAS;IACtB,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,YAAY,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,QAAQ,EAAE,OAAO,CAAC;CACrB;AAKD;;;;;;;;;GASG;AACH,qBAAa,SAAS;IASN,SAAS,CAAC,UAAU,EAAE,MAAM;IAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,QAAQ;IAAE,SAAS,CAAC,IAAI,EAAE,MAAM;IAR/F,SAAS,CAAC,KAAK,EAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC1C,SAAS,CAAC,KAAK,EAAG,SAAS,CAAC;IAE5B;;;;OAIG;gBACmB,UAAU,EAAE,MAAM,EAAY,QAAQ,CAAC,EAAE,QAAQ,YAAA,EAAY,IAAI,GAAE,MAAqB;IAI9G,OAAO,CAAC,iBAAiB;IAWzB;;;;OAIG;IACI,iBAAiB,IAAI,IAAI;IAIhC,iFAAiF;cACjE,0BAA0B,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAqBpF,SAAS,CAAC,qBAAqB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO;IASpD,SAAS,CAAC,kBAAkB,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,GAAG,IAAI;CAU1D"}

package/dist/actor-base.js

@@ -0,0 +1,87 @@
+import { HttpAgent, Actor } from "@icp-sdk/core/agent";
+import { idlFactory } from "../declarations/sultana-assets-rust/sultana-assets-rust.did.js";
+import { DEFAULT_HOST } from "./constants.js";
+// IC error code of an explicit trap (ic0.trap — every ic_cdk::trap and every Rust panic).
+const TRAP_ERROR_CODE = "IC0503";
+/**
+ * Base class for every per-domain actor wrapper (AssetsRustUploadsActor, …). Builds the
+ * HttpAgent + raw candid actor and owns the single choke point that turns the agent's
+ * failures into the three errors every wrapper package throws:
+ * - a trap is thrown as `Error("CanisterError", { cause: {errorKey: "Trap", errorMessage, rawError} })`
+ *   — sultana-assets-rust returns no Framework.Result, it returns the value or traps;
+ * - an inspect-stage rejection is thrown as `Error("CallRefusedAtInspectionStage")`;
+ * - any other failure (unreachable canister, out of cycles, bad reply) is thrown as
+ *   `Error("CriticalCanisterError", { cause: {logs: null, rawError} })`.
+ */
+export class ActorBase {
+    canisterId;
+    identity;
+    host;
+    actor;
+    agent;
+    /**
+     * @param canisterId - The sultana-assets-rust canister to talk to.
+     * @param identity - The caller; left out = anonymous (enough for the reads).
+     * @param host - The IC API host; default https://icp0.io.
+     */
+    constructor(canisterId, identity, host = DEFAULT_HOST) {
+        this.canisterId = canisterId;
+        this.identity = identity;
+        this.host = host;
+        this.initAgentAndActor();
+    }
+    initAgentAndActor() {
+        this.agent = HttpAgent.createSync({
+            host: this.host,
+            identity: this.identity,
+        });
+        this.actor = Actor.createActor(idlFactory, {
+            agent: this.agent,
+            canisterId: this.canisterId,
+        });
+    }
+    /**
+     * Rebuilds the HttpAgent and the actor from scratch — for long-lived consumers after a
+     * streak of failed calls, where a stale agent/connection is the usual suspect. Safe to
+     * call at any time.
+     */
+    reinitializeAgent() {
+        this.initAgentAndActor();
+    }
+    /** Runs one canister call and translates its failure (see the class comment). */
+    async executeFunctionAsyncUnsafe(fnAsync) {
+        try {
+            return await fnAsync();
+        }
+        catch (err) {
+            if (this.isInspectionRejection(err)) {
+                throw new Error("CallRefusedAtInspectionStage", { cause: err });
+            }
+            const trapMessage = this.extractTrapMessage(err);
+            if (trapMessage !== null) {
+                const cause = { errorKey: "Trap", errorMessage: trapMessage, rawError: err };
+                throw new Error("CanisterError", { cause });
+            }
+            throw new Error("CriticalCanisterError", { cause: { logs: null, rawError: err } });
+        }
+    }
+    // True if `error` is an IC reject caused by an inspect-stage refusal. sultana-assets-rust
+    // has no inspect_message today; kept so the error vocabulary stays the same as in the
+    // other wrapper packages. When the canister gets one, check the text it produces.
+    isInspectionRejection(error) {
+        const rejectText = error?.cause?.code?.rejectMessage || error?.message || "";
+        return rejectText.includes("canister_inspect_message explicitly refused message");
+    }
+    // The trap text when `error` is a trap of the canister, otherwise null. The replica
+    // reports it as "... Canister called `ic0.trap` with message: '<text>'.\nConsider ...";
+    // when the text cannot be cut out, the whole reject message is returned.
+    extractTrapMessage(error) {
+        const code = error?.cause?.code;
+        const rejectMessage = typeof code?.rejectMessage === "string" ? code.rejectMessage : "";
+        const isTrap = code?.rejectErrorCode === TRAP_ERROR_CODE || rejectMessage.includes("ic0.trap") || rejectMessage.includes("trapped explicitly");
+        if (!rejectMessage || !isTrap)
+            return null;
+        const match = rejectMessage.match(/with message: '([\s\S]*)'\./);
+        return match ? match[1] : rejectMessage;
+    }
+}

package/dist/actors/admin-actor.d.ts

@@ -0,0 +1,72 @@
+import { ActorBase } from "../actor-base.js";
+import type { WorkerView } from "../interfaces.js";
+/**
+ * Administration of sultana-assets-rust. There is no admin identity on this canister:
+ * administration goes THROUGH sultana-core-motoko — core's superadmin calls proxy endpoints
+ * on core (setAssetWorkers, deleteAssetRaw) and core forwards them here. The core-only
+ * methods below therefore answer `false` (or trap) for every caller but the configured core
+ * canister; they are here for wiring scripts, tests and diagnosis.
+ */
+export declare class AssetsRustAdminActor extends ActorBase {
+    /**
+     * Claim-once bootstrap: while no core canister is configured anyone may set it (call it
+     * right after a deploy); afterwards only the current core canister may re-point it.
+     * @param corePrincipal - The sultana-core-motoko canister this canister trusts.
+     * @returns A Promise that resolves to `true` when set, `false` when the seat is taken by
+     *          another principal than the caller.
+     * @throws CanisterError - The canister trapped.
+     * @throws CallRefusedAtInspectionStage - The call was refused at the inspect stage.
+     * @throws CriticalCanisterError - Transport failure or an unreachable canister.
+     */
+    setCoreCanisterAsyncUnsafe(corePrincipal: string): Promise<boolean>;
+    /**
+     * @returns A Promise that resolves to the trusted core canister, or `null` when none is
+     *          configured yet (a fresh deploy).
+     * @throws CanisterError - The canister trapped.
+     * @throws CallRefusedAtInspectionStage - The call was refused at the inspect stage.
+     * @throws CriticalCanisterError - Transport failure or an unreachable canister.
+     */
+    getCoreCanisterAsyncUnsafe(): Promise<string | null>;
+    /**
+     * Core-canister only: replaces the transcoding-worker list. The real path is core's
+     * superadmin proxy (sultana-core-motoko-package `AdminActor.setAssetWorkersAsyncUnsafe`).
+     * @param workers - Each worker's identity and its FULL upload-endpoint URL.
+     * @returns A Promise that resolves to `true` when replaced, `false` when the caller is
+     *          not the core canister.
+     * @throws CanisterError - The canister trapped.
+     * @throws CallRefusedAtInspectionStage - The call was refused at the inspect stage.
+     * @throws CriticalCanisterError - Transport failure or an unreachable canister.
+     */
+    setWorkersAsyncUnsafe(workers: WorkerView[]): Promise<boolean>;
+    /**
+     * @returns A Promise that resolves to the configured transcoding workers (empty on a
+     *          fresh deploy).
+     * @throws CanisterError - The canister trapped.
+     * @throws CallRefusedAtInspectionStage - The call was refused at the inspect stage.
+     * @throws CriticalCanisterError - Transport failure or an unreachable canister.
+     */
+    getWorkersAsyncUnsafe(): Promise<WorkerView[]>;
+    /**
+     * Core-canister only: raw removal of an asset's bytes (and its thumb or poster) with no
+     * core deregister — cleanup of orphaned bytes. The real path is core's superadmin proxy
+     * `deleteAssetRaw`.
+     * @param assetId - The asset to remove.
+     * @returns A Promise that resolves to `true` when removed, `false` when the caller is not
+     *          the core canister or the asset does not exist.
+     * @throws CanisterError - The canister trapped.
+     * @throws CallRefusedAtInspectionStage - The call was refused at the inspect stage.
+     * @throws CriticalCanisterError - Transport failure or an unreachable canister.
+     */
+    deleteAssetAsyncUnsafe(assetId: string): Promise<boolean>;
+    /**
+     * Core-canister only: runs the stale-reservation sweep now (the canister also runs it
+     * every hour). Reservations older than `ttlMs` are marked failed in core and dropped.
+     * @param ttlMs - Age in milliseconds after which a reservation counts as stale.
+     * @returns A Promise that resolves to the number of reservations swept.
+     * @throws CanisterError - The canister trapped: "caller is not the core canister".
+     * @throws CallRefusedAtInspectionStage - The call was refused at the inspect stage.
+     * @throws CriticalCanisterError - Transport failure or an unreachable canister.
+     */
+    runReservationSweepAsyncUnsafe(ttlMs: number): Promise<number>;
+}
+//# sourceMappingURL=admin-actor.d.ts.map

package/dist/actors/admin-actor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-actor.d.ts","sourceRoot":"","sources":["../../src/actors/admin-actor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IAC/C;;;;;;;;;OASG;IACU,0BAA0B,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIhF;;;;;;OAMG;IACU,0BAA0B,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAKjE;;;;;;;;;OASG;IACU,qBAAqB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAI3E;;;;;;OAMG;IACU,qBAAqB,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAK3D;;;;;;;;;;OAUG;IACU,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAItE;;;;;;;;OAQG;IACU,8BAA8B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAG9E"}