@jsm-mit/chat-motoko-package 0.1.0

package/declarations/chat-motoko-backend/chat-motoko-backend.did.js

@@ -0,0 +1,198 @@
+export const idlFactory = ({ IDL }) => {
+  const AddAdminArgs = IDL.Record({ 'principal' : IDL.Principal });
+  const ErrorDetails = IDL.Variant({
+    'InterCanisterConnectionError' : IDL.Null,
+    'RemoteCanisterError' : IDL.Text,
+    'NotFound' : IDL.Null,
+    'NotAuthorized' : IDL.Text,
+    'InvalidData' : IDL.Text,
+    'AlreadyExists' : IDL.Null,
+    'ReturnsNull' : IDL.Null,
+  });
+  const Error = IDL.Record({ 'details' : ErrorDetails, 'logsJson' : IDL.Text });
+  const Result_2 = IDL.Variant({ 'ok' : IDL.Bool, 'err' : Error });
+  const ChatId = IDL.Text;
+  const CloseChatArgs = IDL.Record({ 'chatId' : ChatId });
+  const ChatStatus = IDL.Variant({ 'closed' : IDL.Null, 'open' : IDL.Null });
+  const Role = IDL.Variant({
+    'member' : IDL.Null,
+    'admin' : IDL.Null,
+    'agent' : IDL.Null,
+    'owner' : IDL.Null,
+  });
+  const Member = IDL.Record({
+    'principal' : IDL.Principal,
+    'joinedAt' : IDL.Int,
+    'role' : Role,
+    'lastReadSeq' : IDL.Nat,
+  });
+  const ProjectId = IDL.Text;
+  const Policy = IDL.Record({ 'agentsReply' : IDL.Bool });
+  const Chat = IDL.Record({
+    'id' : ChatId,
+    'status' : ChatStatus,
+    'title' : IDL.Opt(IDL.Text),
+    'members' : IDL.Vec(Member),
+    'lastMessageAt' : IDL.Int,
+    'subject' : IDL.Opt(IDL.Text),
+    'createdAt' : IDL.Int,
+    'createdBy' : IDL.Principal,
+    'projectId' : ProjectId,
+    'lastSeq' : IDL.Nat,
+    'policy' : Policy,
+  });
+  const Result_1 = IDL.Variant({ 'ok' : Chat, 'err' : Error });
+  const MemberInput = IDL.Record({
+    'principal' : IDL.Principal,
+    'role' : Role,
+  });
+  const CreateChatArgs = IDL.Record({
+    'title' : IDL.Opt(IDL.Text),
+    'members' : IDL.Vec(MemberInput),
+    'subject' : IDL.Opt(IDL.Text),
+    'projectId' : ProjectId,
+    'firstMessage' : IDL.Opt(IDL.Text),
+    'policy' : IDL.Opt(Policy),
+  });
+  const CreateProjectArgs = IDL.Record({
+    'id' : ProjectId,
+    'agents' : IDL.Vec(IDL.Principal),
+    'admins' : IDL.Vec(IDL.Principal),
+    'agentsMayInvite' : IDL.Bool,
+    'defaultPolicy' : Policy,
+  });
+  const Project = IDL.Record({
+    'id' : ProjectId,
+    'createdAt' : IDL.Int,
+    'createdBy' : IDL.Principal,
+    'agents' : IDL.Vec(IDL.Principal),
+    'admins' : IDL.Vec(IDL.Principal),
+    'agentsMayInvite' : IDL.Bool,
+    'defaultPolicy' : Policy,
+  });
+  const Result = IDL.Variant({ 'ok' : Project, 'err' : Error });
+  const Result_9 = IDL.Variant({
+    'ok' : IDL.Vec(IDL.Principal),
+    'err' : Error,
+  });
+  const GetChatArgs = IDL.Record({ 'chatId' : ChatId });
+  const GetMessagesArgs = IDL.Record({
+    'limit' : IDL.Opt(IDL.Nat),
+    'chatId' : ChatId,
+    'sinceSeq' : IDL.Nat,
+  });
+  const SystemEvent = IDL.Variant({
+    'memberJoined' : IDL.Record({ 'principal' : IDL.Principal, 'role' : Role }),
+    'policyChanged' : Policy,
+    'memberRemoved' : IDL.Record({
+      'by' : IDL.Principal,
+      'principal' : IDL.Principal,
+    }),
+    'memberLeft' : IDL.Record({ 'principal' : IDL.Principal }),
+    'chatCreated' : IDL.Null,
+    'chatClosed' : IDL.Null,
+    'memberInvited' : IDL.Record({
+      'by' : IDL.Principal,
+      'principal' : IDL.Principal,
+      'role' : Role,
+    }),
+  });
+  const MessageKind = IDL.Variant({
+    'toolTrace' : IDL.Null,
+    'text' : IDL.Null,
+    'event' : SystemEvent,
+  });
+  const Message = IDL.Record({
+    'seq' : IDL.Nat,
+    'kind' : MessageKind,
+    'createdAt' : IDL.Int,
+    'text' : IDL.Text,
+    'globalSeq' : IDL.Nat,
+    'author' : IDL.Principal,
+    'projectId' : ProjectId,
+    'chatId' : ChatId,
+  });
+  const MessagesPage = IDL.Record({
+    'messages' : IDL.Vec(Message),
+    'lastSeq' : IDL.Nat,
+  });
+  const Result_8 = IDL.Variant({ 'ok' : MessagesPage, 'err' : Error });
+  const GetMyChatsArgs = IDL.Record({
+    'subject' : IDL.Opt(IDL.Text),
+    'includeClosed' : IDL.Bool,
+    'limit' : IDL.Opt(IDL.Nat),
+    'projectId' : ProjectId,
+  });
+  const Result_7 = IDL.Variant({ 'ok' : IDL.Vec(Chat), 'err' : Error });
+  const GetProjectArgs = IDL.Record({ 'projectId' : ProjectId });
+  const InviteMemberArgs = IDL.Record({
+    'principal' : IDL.Principal,
+    'role' : Role,
+    'chatId' : ChatId,
+  });
+  const LeaveChatArgs = IDL.Record({ 'chatId' : ChatId });
+  const ListProjectsArgs = IDL.Record({ 'limit' : IDL.Opt(IDL.Nat) });
+  const Result_6 = IDL.Variant({ 'ok' : IDL.Vec(Project), 'err' : Error });
+  const MarkReadArgs = IDL.Record({ 'seq' : IDL.Nat, 'chatId' : ChatId });
+  const PollNewMessagesArgs = IDL.Record({
+    'limit' : IDL.Opt(IDL.Nat),
+    'sinceGlobalSeq' : IDL.Nat,
+  });
+  const PollResult = IDL.Record({
+    'nextSinceGlobalSeq' : IDL.Nat,
+    'headGlobalSeq' : IDL.Nat,
+    'messages' : IDL.Vec(Message),
+  });
+  const Result_5 = IDL.Variant({ 'ok' : PollResult, 'err' : Error });
+  const PostKind = IDL.Variant({ 'toolTrace' : IDL.Null, 'text' : IDL.Null });
+  const PostArgs = IDL.Record({
+    'kind' : PostKind,
+    'text' : IDL.Text,
+    'chatId' : ChatId,
+  });
+  const Result_4 = IDL.Variant({ 'ok' : Message, 'err' : Error });
+  const PurgeChatArgs = IDL.Record({ 'chatId' : ChatId });
+  const Result_3 = IDL.Variant({ 'ok' : IDL.Principal, 'err' : Error });
+  const RemoveAdminArgs = IDL.Record({ 'principal' : IDL.Principal });
+  const RemoveMemberArgs = IDL.Record({
+    'principal' : IDL.Principal,
+    'chatId' : ChatId,
+  });
+  const SetLoggingEnabledArgs = IDL.Record({ 'enabled' : IDL.Bool });
+  const SetPolicyArgs = IDL.Record({ 'chatId' : ChatId, 'policy' : Policy });
+  const UpdateProjectArgs = IDL.Record({
+    'agents' : IDL.Opt(IDL.Vec(IDL.Principal)),
+    'projectId' : ProjectId,
+    'admins' : IDL.Opt(IDL.Vec(IDL.Principal)),
+    'agentsMayInvite' : IDL.Opt(IDL.Bool),
+    'defaultPolicy' : IDL.Opt(Policy),
+  });
+  return IDL.Service({
+    'addAdmin' : IDL.Func([AddAdminArgs], [Result_2], []),
+    'clearLogs' : IDL.Func([], [], []),
+    'closeChat' : IDL.Func([CloseChatArgs], [Result_1], []),
+    'createChat' : IDL.Func([CreateChatArgs], [Result_1], []),
+    'createProject' : IDL.Func([CreateProjectArgs], [Result], []),
+    'getAdmins' : IDL.Func([], [Result_9], ['query']),
+    'getChat' : IDL.Func([GetChatArgs], [Result_1], ['query']),
+    'getLogs' : IDL.Func([], [IDL.Text], ['query']),
+    'getMessages' : IDL.Func([GetMessagesArgs], [Result_8], ['query']),
+    'getMyChats' : IDL.Func([GetMyChatsArgs], [Result_7], ['query']),
+    'getProject' : IDL.Func([GetProjectArgs], [Result], ['query']),
+    'inviteMember' : IDL.Func([InviteMemberArgs], [Result_1], []),
+    'leaveChat' : IDL.Func([LeaveChatArgs], [Result_2], []),
+    'listProjects' : IDL.Func([ListProjectsArgs], [Result_6], ['query']),
+    'markRead' : IDL.Func([MarkReadArgs], [Result_2], []),
+    'pollNewMessages' : IDL.Func([PollNewMessagesArgs], [Result_5], ['query']),
+    'post' : IDL.Func([PostArgs], [Result_4], []),
+    'purgeChat' : IDL.Func([PurgeChatArgs], [Result_2], []),
+    'registerAsAdmin' : IDL.Func([], [Result_3], []),
+    'removeAdmin' : IDL.Func([RemoveAdminArgs], [Result_2], []),
+    'removeMember' : IDL.Func([RemoveMemberArgs], [Result_1], []),
+    'setLoggingEnabled' : IDL.Func([SetLoggingEnabledArgs], [Result_2], []),
+    'setPolicy' : IDL.Func([SetPolicyArgs], [Result_1], []),
+    'updateProject' : IDL.Func([UpdateProjectArgs], [Result], []),
+    'whoAmI' : IDL.Func([], [IDL.Principal], ['query']),
+  });
+};
+export const init = ({ IDL }) => { return []; };

package/declarations/chat-motoko-backend/index.d.ts

@@ -0,0 +1,50 @@
+import type {
+  ActorSubclass,
+  HttpAgentOptions,
+  ActorConfig,
+  Agent,
+} from "@icp-sdk/core/agent";
+import type { Principal } from "@icp-sdk/core/principal";
+import type { IDL } from "@icp-sdk/core/candid";
+
+import { _SERVICE } from './chat-motoko-backend.did';
+
+export declare const idlFactory: IDL.InterfaceFactory;
+export declare const canisterId: string;
+
+export declare interface CreateActorOptions {
+  /**
+   * @see {@link Agent}
+   */
+  agent?: Agent;
+  /**
+   * @see {@link HttpAgentOptions}
+   */
+  agentOptions?: HttpAgentOptions;
+  /**
+   * @see {@link ActorConfig}
+   */
+  actorOptions?: ActorConfig;
+}
+
+/**
+ * Intializes an {@link ActorSubclass}, configured with the provided SERVICE interface of a canister.
+ * @constructs {@link ActorSubClass}
+ * @param {string | Principal} canisterId - ID of the canister the {@link Actor} will talk to
+ * @param {CreateActorOptions} options - see {@link CreateActorOptions}
+ * @param {CreateActorOptions["agent"]} options.agent - a pre-configured agent you'd like to use. Supercedes agentOptions
+ * @param {CreateActorOptions["agentOptions"]} options.agentOptions - options to set up a new agent
+ * @see {@link HttpAgentOptions}
+ * @param {CreateActorOptions["actorOptions"]} options.actorOptions - options for the Actor
+ * @see {@link ActorConfig}
+ */
+export declare const createActor: (
+  canisterId: string | Principal,
+  options?: CreateActorOptions
+) => ActorSubclass<_SERVICE>;
+
+/**
+ * Intialized Actor using default settings, ready to talk to a canister using its candid interface
+ * @constructs {@link ActorSubClass}
+ */
+export declare const chat_motoko_backend: ActorSubclass<_SERVICE>;

package/declarations/chat-motoko-backend/index.js

@@ -0,0 +1,42 @@
+import { Actor, HttpAgent } from "@icp-sdk/core/agent";
+
+// Imports and re-exports candid interface
+import { idlFactory } from "./chat-motoko-backend.did.js";
+export { idlFactory } from "./chat-motoko-backend.did.js";
+
+/* CANISTER_ID is replaced by webpack based on node environment
+ * Note: canister environment variable will be standardized as
+ * process.env.CANISTER_ID_<CANISTER_NAME_UPPERCASE>
+ * beginning in dfx 0.15.0
+ */
+export const canisterId =
+  process.env.CANISTER_ID_CHAT_MOTOKO_BACKEND;
+
+export const createActor = (canisterId, options = {}) => {
+  const agent = options.agent || new HttpAgent({ ...options.agentOptions });
+
+  if (options.agent && options.agentOptions) {
+    console.warn(
+      "Detected both agent and agentOptions passed to createActor. Ignoring agentOptions and proceeding with the provided agent."
+    );
+  }
+
+  // Fetch root key for certificate validation during development
+  if (process.env.DFX_NETWORK !== "ic") {
+    agent.fetchRootKey().catch((err) => {
+      console.warn(
+        "Unable to fetch root key. Check to ensure that your local replica is running"
+      );
+      console.error(err);
+    });
+  }
+
+  // Creates an actor with using the candid interface and the HttpAgent
+  return Actor.createActor(idlFactory, {
+    agent,
+    canisterId,
+    ...options.actorOptions,
+  });
+};
+
+export const chat_motoko_backend = canisterId ? createActor(canisterId) : undefined;

package/dist/actor-base.d.ts

@@ -0,0 +1,47 @@
+import { type ActorSubclass, HttpAgent, type Identity } from "@icp-sdk/core/agent";
+import type { _SERVICE, Error as ErrorFromCanister } from "../declarations/chat-motoko-backend/chat-motoko-backend.did.js";
+export interface LogEntry {
+    id: number;
+    message: string;
+}
+/**
+ * Base class for every per-domain actor wrapper (ChatsActor, MessagesActor, …). Builds the
+ * HttpAgent + raw candid actor and owns the single choke point that turns the canister's
+ * Framework.Result<T> into idiomatic TS:
+ * - `{ok: T}` resolves with `T` directly.
+ * - `{err: ...}` is thrown as `Error("CanisterError", { cause: {errorKey, errorMessage, logs} })`.
+ * - An `inspect()`-stage rejection is thrown as `Error("CallRefusedAtInspectionStage")`.
+ * - Any other transport failure is thrown as `Error("CriticalCanisterError")`.
+ */
+export declare class ActorBase {
+    protected canisterId: string;
+    protected identity?: Identity | undefined;
+    protected actor: ActorSubclass<_SERVICE>;
+    protected agent: HttpAgent;
+    constructor(canisterId: string, identity?: Identity | undefined);
+    private initAgentAndActor;
+    /**
+     * Rebuilds the HttpAgent and the actor from scratch. Long-lived consumers (e.g.
+     * ChatPoller) call this after a prolonged streak of failed calls, where a stale
+     * agent/connection is the usual suspect. Safe to call at any time.
+     */
+    reinitializeAgent(): void;
+    protected executeFunctionAsyncUnsafe<T>(fnAsync: () => Promise<{
+        ok: T;
+    } | {
+        err: ErrorFromCanister;
+    }>): Promise<T>;
+    /**
+     * For the few diagnostic methods that do NOT return a Framework.Result (whoAmI,
+     * getLogs, clearLogs) — only the transport-level error translation applies.
+     */
+    protected executeRawAsyncUnsafe<T>(fnAsync: () => Promise<T>): Promise<T>;
+    protected handleResultErrors(errorFromCanister: ErrorFromCanister): {
+        errorKey: string;
+        errorMessage: any;
+        logs: LogEntry[];
+    };
+    protected isInspectionRejection(error: any): boolean;
+    protected extractLogsFromError(error: any): LogEntry[] | 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,KAAK,IAAI,iBAAiB,EAAE,MAAM,gEAAgE,CAAC;AAG3H,MAAM,WAAW,QAAQ;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,qBAAa,SAAS;IAIN,SAAS,CAAC,UAAU,EAAE,MAAM;IAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,QAAQ;IAHvE,SAAS,CAAC,KAAK,EAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC1C,SAAS,CAAC,KAAK,EAAG,SAAS,CAAC;gBAEN,UAAU,EAAE,MAAM,EAAY,QAAQ,CAAC,EAAE,QAAQ,YAAA;IAIvE,OAAO,CAAC,iBAAiB;IAWzB;;;;OAIG;IACI,iBAAiB,IAAI,IAAI;cAIhB,0BAA0B,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;QAAE,EAAE,EAAE,CAAC,CAAA;KAAE,GAAG;QAAE,GAAG,EAAE,iBAAiB,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAmCzH;;;OAGG;cACa,qBAAqB,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAW/E,SAAS,CAAC,kBAAkB,CAAC,iBAAiB,EAAE,iBAAiB;;;;;IAkBjE,SAAS,CAAC,qBAAqB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO;IAWpD,SAAS,CAAC,oBAAoB,CAAC,KAAK,EAAE,GAAG,GAAG,QAAQ,EAAE,GAAG,IAAI;CAwBhE"}

package/dist/actor-base.js

@@ -0,0 +1,130 @@
+import { HttpAgent, Actor } from "@icp-sdk/core/agent";
+import { idlFactory } from "../declarations/chat-motoko-backend/index.js";
+import { BetterJSON } from "@jsm-mit/utils-package";
+/**
+ * Base class for every per-domain actor wrapper (ChatsActor, MessagesActor, …). Builds the
+ * HttpAgent + raw candid actor and owns the single choke point that turns the canister's
+ * Framework.Result<T> into idiomatic TS:
+ * - `{ok: T}` resolves with `T` directly.
+ * - `{err: ...}` is thrown as `Error("CanisterError", { cause: {errorKey, errorMessage, logs} })`.
+ * - An `inspect()`-stage rejection is thrown as `Error("CallRefusedAtInspectionStage")`.
+ * - Any other transport failure is thrown as `Error("CriticalCanisterError")`.
+ */
+export class ActorBase {
+    canisterId;
+    identity;
+    actor;
+    agent;
+    constructor(canisterId, identity) {
+        this.canisterId = canisterId;
+        this.identity = identity;
+        this.initAgentAndActor();
+    }
+    initAgentAndActor() {
+        this.agent = HttpAgent.createSync({
+            host: "https://icp0.io",
+            identity: this.identity,
+        });
+        this.actor = Actor.createActor(idlFactory, {
+            agent: this.agent,
+            canisterId: this.canisterId,
+        });
+    }
+    /**
+     * Rebuilds the HttpAgent and the actor from scratch. Long-lived consumers (e.g.
+     * ChatPoller) call this after a prolonged streak of failed calls, where a stale
+     * agent/connection is the usual suspect. Safe to call at any time.
+     */
+    reinitializeAgent() {
+        this.initAgentAndActor();
+    }
+    async executeFunctionAsyncUnsafe(fnAsync) {
+        let errorObj = {};
+        try {
+            const result = await fnAsync();
+            if ("ok" in result) {
+                return result.ok;
+            }
+            errorObj = this.handleResultErrors(result.err);
+        }
+        catch (err) {
+            // The canister's `system func inspect` rejected the call before it was ever
+            // decoded or executed (oversized payload or anonymous caller). This is a
+            // transport-level IC reject, not a decoded Framework.Result — there's never any
+            // Framework log to extract, and it's not a real "canister unreachable/crashed"
+            // scenario either, so it gets its own distinct error.
+            if (this.isInspectionRejection(err)) {
+                throw new Error("CallRefusedAtInspectionStage", { cause: err });
+            }
+            // No console output here — whatever was extractable is passed forward on `cause`
+            // instead, so callers can inspect it themselves rather than it only ever being
+            // printed and lost.
+            const logs = this.extractLogsFromError(err);
+            throw new Error("CriticalCanisterError", { cause: { logs, rawError: err } });
+        }
+        if (errorObj) {
+            throw new Error("CanisterError", { cause: errorObj });
+        }
+        else {
+            throw new Error("UnreachableCodeError", { cause: "Reached a code path that should be unreachable after error handling. Location Id: CHOPA" });
+        }
+    }
+    /**
+     * For the few diagnostic methods that do NOT return a Framework.Result (whoAmI,
+     * getLogs, clearLogs) — only the transport-level error translation applies.
+     */
+    async executeRawAsyncUnsafe(fnAsync) {
+        try {
+            return await fnAsync();
+        }
+        catch (err) {
+            if (this.isInspectionRejection(err)) {
+                throw new Error("CallRefusedAtInspectionStage", { cause: err });
+            }
+            throw new Error("CriticalCanisterError", { cause: { logs: null, rawError: err } });
+        }
+    }
+    handleResultErrors(errorFromCanister) {
+        const logs = BetterJSON.parse(errorFromCanister.logsJson, false);
+        const error = errorFromCanister.details;
+        const errorKey = Object.keys(error)[0];
+        const errorMessage = error[errorKey];
+        return {
+            errorKey: errorKey.toString(),
+            errorMessage,
+            logs,
+        };
+    }
+    // True if `error` is an IC transport-level reject caused by `system func inspect`
+    // returning false (`canister_inspect_message explicitly refused message`, IC0503).
+    // This text is a fixed IC/Motoko runtime message — it does not vary by which inspect
+    // check failed.
+    isInspectionRejection(error) {
+        const rejectText = error?.cause?.code?.rejectMessage ||
+            error?.message ||
+            "";
+        return rejectText.includes("canister_inspect_message explicitly refused message");
+    }
+    // On a trap, Logs.interrupt appends the request's log trail as a JSON array to the
+    // reject message — best-effort recovery of that array from the raw reject text.
+    extractLogsFromError(error) {
+        try {
+            const rejectMessage = error?.cause?.code?.rejectMessage ||
+                error?.message ||
+                "";
+            if (!rejectMessage)
+                return null;
+            const jsonStartIdx = rejectMessage.indexOf("[{");
+            const jsonEndIdx = rejectMessage.lastIndexOf("}]");
+            if (jsonStartIdx === -1 || jsonEndIdx === -1) {
+                return null;
+            }
+            const rawJson = rejectMessage.substring(jsonStartIdx, jsonEndIdx + 2);
+            const logs = JSON.parse(rawJson);
+            return logs;
+        }
+        catch (e) {
+            return null;
+        }
+    }
+}

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

@@ -0,0 +1,61 @@
+import { type Identity } from "@icp-sdk/core/agent";
+import { ActorBase } from "../actor-base.js";
+/** 1:1 wrapper for the canister's AdminController plus the three diagnostics. */
+export declare class AdminActor extends ActorBase {
+    constructor(canisterId: string, identity?: Identity);
+    /**
+     * Bootstrap: succeeds only while the canister has NO admin at all — the first caller
+     * claims the admin role. Once any admin exists this always refuses.
+     * @returns The principal (text) that became admin, i.e. the caller.
+     * @throws Error with message `CanisterError` when the canister returns a business error (errorKey `NotAuthorized` when an admin already exists). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    registerAsAdminAsyncUnsafe(): Promise<string>;
+    /**
+     * Adds a principal to the admin allowlist. Admin only.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized, `AlreadyExists`, anonymous principal). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    addAdminAsyncUnsafe(principal: string): Promise<boolean>;
+    /**
+     * Removes a principal from the admin allowlist; the last admin cannot be removed. Admin only.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized, `NotFound`, last admin). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    removeAdminAsyncUnsafe(principal: string): Promise<boolean>;
+    /**
+     * The admin allowlist. Admin only.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    getAdminsAsyncUnsafe(): Promise<string[]>;
+    /**
+     * The logging kill switch. Admin only.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    setLoggingEnabledAsyncUnsafe(enabled: boolean): Promise<boolean>;
+    /**
+     * The caller's principal as the canister sees it (text).
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    whoAmIAsyncUnsafe(): Promise<string>;
+    /**
+     * Leftover request logs as JSON text (normally empty — logs are cleared per request).
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister.
+     */
+    getLogsAsyncUnsafe(): Promise<string>;
+    /**
+     * Clears leftover request logs.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    clearLogsAsyncUnsafe(): Promise<void>;
+}
+//# 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":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,iFAAiF;AACjF,qBAAa,UAAW,SAAQ,SAAS;gBAEzB,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ;IAInD;;;;;;;OAOG;IACU,0BAA0B,IAAI,OAAO,CAAC,MAAM,CAAC;IAK1D;;;;;OAKG;IACU,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrE;;;;;OAKG;IACU,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIxE;;;;;OAKG;IACU,oBAAoB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAKtD;;;;;OAKG;IACU,4BAA4B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAI7E;;;;OAIG;IACU,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IAKjD;;;OAGG;IACU,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC;IAIlD;;;;OAIG;IACU,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC;CAGrD"}

package/dist/actors/admin-actor.js

@@ -0,0 +1,82 @@
+import {} from "@icp-sdk/core/agent";
+import { Principal } from "@icp-sdk/core/principal";
+import { ActorBase } from "../actor-base.js";
+/** 1:1 wrapper for the canister's AdminController plus the three diagnostics. */
+export class AdminActor extends ActorBase {
+    constructor(canisterId, identity) {
+        super(canisterId, identity);
+    }
+    /**
+     * Bootstrap: succeeds only while the canister has NO admin at all — the first caller
+     * claims the admin role. Once any admin exists this always refuses.
+     * @returns The principal (text) that became admin, i.e. the caller.
+     * @throws Error with message `CanisterError` when the canister returns a business error (errorKey `NotAuthorized` when an admin already exists). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    async registerAsAdminAsyncUnsafe() {
+        const principal = await this.executeFunctionAsyncUnsafe(() => this.actor.registerAsAdmin());
+        return principal.toText();
+    }
+    /**
+     * Adds a principal to the admin allowlist. Admin only.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized, `AlreadyExists`, anonymous principal). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    async addAdminAsyncUnsafe(principal) {
+        return this.executeFunctionAsyncUnsafe(() => this.actor.addAdmin({ principal: Principal.fromText(principal) }));
+    }
+    /**
+     * Removes a principal from the admin allowlist; the last admin cannot be removed. Admin only.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized, `NotFound`, last admin). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    async removeAdminAsyncUnsafe(principal) {
+        return this.executeFunctionAsyncUnsafe(() => this.actor.removeAdmin({ principal: Principal.fromText(principal) }));
+    }
+    /**
+     * The admin allowlist. Admin only.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    async getAdminsAsyncUnsafe() {
+        const admins = await this.executeFunctionAsyncUnsafe(() => this.actor.getAdmins());
+        return admins.map((p) => p.toText());
+    }
+    /**
+     * The logging kill switch. Admin only.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    async setLoggingEnabledAsyncUnsafe(enabled) {
+        return this.executeFunctionAsyncUnsafe(() => this.actor.setLoggingEnabled({ enabled }));
+    }
+    /**
+     * The caller's principal as the canister sees it (text).
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    async whoAmIAsyncUnsafe() {
+        const principal = await this.executeRawAsyncUnsafe(() => this.actor.whoAmI());
+        return principal.toText();
+    }
+    /**
+     * Leftover request logs as JSON text (normally empty — logs are cleared per request).
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister.
+     */
+    async getLogsAsyncUnsafe() {
+        return this.executeRawAsyncUnsafe(() => this.actor.getLogs());
+    }
+    /**
+     * Clears leftover request logs.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    async clearLogsAsyncUnsafe() {
+        await this.executeRawAsyncUnsafe(() => this.actor.clearLogs());
+    }
+}