@jsm-mit/chat-motoko-package 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# @jsm-mit/chat-motoko-package
+
+TypeScript wrapper for the [`chat-motoko`](../chat-motoko) canister — a generic,
+multi-project, multi-party chat on the Internet Computer — plus the integration tests
+that prove it.
+
+```ts
+import { ChatsActor, MessagesActor, ChatPoller } from "@jsm-mit/chat-motoko-package";
+
+const chats = new ChatsActor(canisterId, identity);
+const chat = await chats.createChatAsyncUnsafe({ projectId: "sultana-dev", subject: salonId, firstMessage: "cześć" });
+
+const messages = new MessagesActor(canisterId, identity);
+await messages.postAsyncUnsafe({ chatId: chat.id, text: "dodaj usługę strzyżenie" });
+const page = await messages.getMessagesAsyncUnsafe({ chatId: chat.id, sinceSeq: 0 });
+
+// An agent host: every new message in every chat this identity belongs to.
+const poller = new ChatPoller(messages, 1000, { onError: console.error });
+poller.messages$.subscribe((m) => console.log(m.chatId, m.kind, m.text));
+poller.run();
+```
+
+One class per canister controller (`AdminActor`, `ProjectsActor`, `ChatsActor`,
+`MessagesActor`), every method `…AsyncUnsafe` (throws one of `CanisterError`,
+`CriticalCanisterError`, `CallRefusedAtInspectionStage`) or `…AsyncSafe` (never
+throws). Views translate `Principal` → text, `opt` → optional, variants → string
+unions; sequence numbers are plain `number`s, timestamps `bigint` nanoseconds.
+
+`src/` is browser-safe — the same package serves the agent host and a web panel.
+
+Scripts: `build`, `typecheck`, `sync-declarations`, `test-suite`,
+`test-access-restrictions`, `sandbox` (an interactive admin/chat console:
+`npm run sandbox -- <canister-id>`). See `CLAUDE.md` for who runs what.
+
+## Publishing
+
+Bump the version in `package.json` by hand, then:
+
+```
+npm run publish-public
+```
+
+`scripts/publish-public.sh` refuses unless this repo is on `master` equal to
+`origin/master` with nothing uncommitted but the bump, and the version is not on the
+registry yet. It then runs `scripts/stamp-canister-commit.sh`, which refuses unless
+`../chat-motoko` is on `master`, clean and equal to its `origin/master`, rebuilds the
+canister, regenerates the declarations and refuses if that changes what is committed
+here. Only then it writes `chatMotoko.{repo, repoUrl, commit}` into `package.json` — the
+canister commit this version was generated from — publishes, and commits and pushes
+`Version bump to <version>`. A failed publish takes the stamp back out.

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

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

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

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