@muhkoo/connect 0.3.0-alpha.0 → 0.4.0-alpha.1

package/dist/connect.d.ts

@@ -936,6 +936,14 @@ declare class EncryptedSession {
 interface WSTransportOptions {
     /** WebSocket URL, e.g. `ws://localhost:8787/foo`. */
     url: string;
+    /**
+     * Optional async provider for a FRESH connection URL, called before each
+     * RECONNECT. Use it when the URL carries a single-use/expiring credential
+     * (e.g. a one-time WS upgrade ticket): on reconnect the baked-in ticket is
+     * already consumed/expired, so without this the reconnect is rejected and the
+     * transport burns through its attempts. The initial connect uses `url` as-is.
+     */
+    urlProvider?: () => string | Promise<string>;
     /**
      * Stable identifier for this connection (a channel / space / personal-space
      * id). Lifecycle + MESSAGE events are namespaced by it on the shared
@@ -991,6 +999,7 @@ declare class WSTransport extends EventCore {
     readonly off: (event: EventCoreEvents, handler: EventListener | CallableFunction) => void;
     private scopedEvent;
     private url;
+    private urlProvider?;
     private socket;
     private _isConnected;
     private _isConnecting;
@@ -1586,6 +1595,12 @@ interface WriteToShardsInput {
      * resumable uploads: the same id always maps to the same manifest slot.
      */
     fileId?: string;
+    /**
+     * Optional upload-progress callback, invoked after each chunk finishes
+     * (`completed` of `total` chunks). Lets a UI show a progress bar. Called once
+     * with `(0, total)` before the first chunk so a bar can render immediately.
+     */
+    onProgress?: (completed: number, total: number) => void;
 }
 declare class FileStorage {
     private readonly space;
@@ -2279,6 +2294,7 @@ declare class HttpClient {
     readonly fetch: typeof fetch;
     get<T = unknown>(path: string): Promise<T>;
     post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown): Promise<T>;
     del<T = unknown>(path: string, body?: unknown): Promise<T>;
     private request;
 }
@@ -2516,6 +2532,23 @@ interface RosterMember {
     /** Base64url-encoded JWK of the member's identity ECDSA public key. */
     identityEcdsaPub?: string;
 }
+/** A shareable invite link to a space. Redeeming it allowlists the holder so
+ *  the keeper admits them. */
+interface InviteLink {
+    /** The capability token; embed in a URL to share. */
+    token: string;
+    /** Member id (username) that created the link. */
+    createdBy?: string;
+    createdAt?: number;
+    /** Epoch ms when the link stops working; 0 = never. */
+    expiresAt?: number;
+    /** Max redemptions; 0 = unlimited. */
+    maxUses?: number;
+    /** Redemptions so far. */
+    uses?: number;
+    /** Access level granted to redeemers ("viewer" | "editor"). */
+    role?: string;
+}
 
 /**
  * PacketCipher — the strategy `Network` uses to seal/open a packet's payload.
@@ -2929,7 +2962,9 @@ declare class Space {
         memberId: string;
         identityEcdhPub: string;
     }>): Promise<number>;
-    putFile(file: File | Blob | Uint8Array, metadata: SpaceFileMetadata): Promise<{
+    putFile(file: File | Blob | Uint8Array, metadata: SpaceFileMetadata, opts?: {
+        onProgress?: (completed: number, total: number) => void;
+    }): Promise<{
         manifest: FileManifest;
         stat: FileStat;
     }>;
@@ -3135,6 +3170,40 @@ declare class SpaceNamespace {
     joinChannel(name: string, opts?: {
         timeoutMs?: number;
     }): Promise<Space>;
+    /** Mint a shareable invite link for a space. `opts.expiresInSec` / `maxUses`
+     *  bound it (0/undefined = unlimited); `opts.role` ("viewer"|"editor") is the
+     *  access granted to redeemers (default viewer). Returns the link. */
+    createInviteLink(spaceId: string, opts?: {
+        expiresInSec?: number;
+        maxUses?: number;
+        role?: string;
+    }): Promise<InviteLink>;
+    /** Set a member's role on a space ("viewer" | "editor"). Owner-only. */
+    setMemberRole(spaceId: string, username: string, role: string): Promise<void>;
+    /** Roster with roles (owner/members only). */
+    members(spaceId: string): Promise<Array<{
+        memberId: string;
+        role: string;
+    }>>;
+    /** List a space's active invite links (creator/members only). */
+    listInviteLinks(spaceId: string): Promise<InviteLink[]>;
+    /** Revoke an invite link by token. */
+    revokeInviteLink(spaceId: string, token: string): Promise<void>;
+    /**
+     * Join a space using an invite link: redeem the token (the keeper admits
+     * this member), then connect and resolve once the group key arrives.
+     * Returns the open {@link Space}.
+     */
+    joinByInvite(spaceId: string, token: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<Space>;
+    /** The current member roster of a space (member id → identity public keys). */
+    roster(spaceId: string): Promise<Array<{
+        memberId: string;
+        identityEcdhPub: string;
+        identityEcdsaPub?: string;
+    }>>;
+    private keyringFor;
     private build;
     /** Ensure the member has an identity keypair; return its public ECDH + ECDSA keys. */
     private ensureIdentity;
@@ -3143,6 +3212,236 @@ declare class SpaceNamespace {
     private myId;
 }
 
+/**
+ * `client.agents` — manage an app's **Programmable Agents** (server-side
+ * "virtual users" backed by Workers AI).
+ *
+ *   const { config } = await client.agents.create(appId, {
+ *     handle: '@assistant', displayName: 'Assistant',
+ *     systemPrompt: 'You are a helpful teammate in this Space.',
+ *     triggers: [{ type: 'mention' }],
+ *   });
+ *   await client.agents.enable(appId, config.agentId, spaceId);  // per-Space opt-in
+ *
+ * These are MANAGEMENT calls — the agent itself runs on the accelerator. Only an
+ * app's owner or an editor of its shared Space may create/update/enable an agent
+ * (viewers can read). Authorization rides the user session token; non-owner
+ * editors pass their management Space via `opts.space`.
+ *
+ * v1 is "prompts + persona": a system prompt, a model, named prompt `skills`,
+ * and `triggers` that decide when the agent speaks. No tools, no code.
+ */
+
+type AgentTriggerType = "mention" | "keyword" | "regex" | "always";
+interface AgentTrigger {
+    type: AgentTriggerType;
+    /** Required for `keyword` (case-insensitive substring) and `regex`. */
+    pattern?: string;
+    /** Name of a {@link AgentSkill} to run on match. */
+    skill?: string;
+}
+interface AgentSkill {
+    name: string;
+    prompt: string;
+}
+interface AgentConfig {
+    agentId: string;
+    /** @-mention target, e.g. "@assistant". */
+    handle: string;
+    displayName: string;
+    model: string;
+    systemPrompt: string;
+    skills: AgentSkill[];
+    triggers: AgentTrigger[];
+    /** Space ids this agent is enabled on (per-Space opt-in). */
+    enabledSpaces: string[];
+    caps: {
+        dailyTokenBudget: number;
+    };
+    createdAt: number;
+    updatedAt: number;
+}
+/** The editor-settable fields when creating an agent. */
+interface AgentCreateInput {
+    handle: string;
+    displayName: string;
+    systemPrompt: string;
+    model?: string;
+    skills?: AgentSkill[];
+    triggers?: AgentTrigger[];
+    caps?: {
+        dailyTokenBudget: number;
+    };
+}
+type AgentUpdateInput = Partial<AgentCreateInput>;
+/** Create/get response — the config plus the agent's published identity keys. */
+interface AgentProvisioned {
+    config: AgentConfig;
+    /** The agent's Space member id (`__agent__:<agentId>`). */
+    memberId: string;
+    /** base64url-JWK identity ECDH public key (null until provisioned). */
+    ecdhPub: string | null;
+    /** base64url-JWK identity ECDSA public key — verifies the agent's messages. */
+    ecdsaPub: string | null;
+}
+interface AgentsNamespaceDeps {
+    http: HttpClient;
+}
+/** Common option: a management Space for delegated (non-owner) access. */
+interface AgentScopeOpts {
+    space?: string;
+}
+declare class AgentsNamespace {
+    private readonly deps;
+    constructor(deps: AgentsNamespaceDeps);
+    /** List the app's agents. */
+    list(appId: string, opts?: AgentScopeOpts): Promise<AgentConfig[]>;
+    /** Read one agent (config + identity keys). */
+    get(appId: string, agentId: string, opts?: AgentScopeOpts): Promise<AgentProvisioned>;
+    /** Create an agent (owner/editor only). */
+    create(appId: string, input: AgentCreateInput, opts?: AgentScopeOpts): Promise<AgentProvisioned>;
+    /** Update an agent's editor-settable fields (owner/editor only). */
+    update(appId: string, agentId: string, patch: AgentUpdateInput, opts?: AgentScopeOpts): Promise<{
+        config: AgentConfig;
+    }>;
+    /** Delete an agent (owner/editor only). */
+    delete(appId: string, agentId: string, opts?: AgentScopeOpts): Promise<{
+        deleted: boolean;
+    }>;
+    /** Enable the agent on a Space (per-Space opt-in). */
+    enable(appId: string, agentId: string, spaceId: string, opts?: AgentScopeOpts): Promise<{
+        config: AgentConfig;
+    }>;
+    /** Disable the agent on a Space. */
+    disable(appId: string, agentId: string, spaceId: string, opts?: AgentScopeOpts): Promise<{
+        config: AgentConfig;
+    }>;
+    private path;
+}
+
+/**
+ * `client.functions` — manage an app's **serverless functions** (developer-
+ * authored code that runs on the accelerator).
+ *
+ *   const { config } = await client.functions.deploy(appId, {
+ *     name: 'hello', displayName: 'Hello',
+ *     code: `export default { fetch: () => new Response('hi') }`,
+ *     triggers: { http: { enabled: true } },
+ *   });
+ *   // HTTP-reachable at  hello--<slug>.fns.muhkoo.dev
+ *   await client.functions.enable(appId, config.functionId, spaceId); // Space-bound
+ *
+ * These are MANAGEMENT calls — the function itself runs on the accelerator
+ * (uploaded just-in-time, decrypted only at invocation). Only an app's owner or
+ * an editor of its shared Space may deploy/update/enable (viewers read).
+ * Authorization rides the user session token; non-owner editors pass their
+ * management Space via `opts.space`.
+ *
+ * v1 is "compute-only": a function is an untrusted single-module ES worker
+ * (`export default { fetch }`) with NO platform bindings — it reaches the
+ * platform as an external client (the end-user session is passed through). Two
+ * triggers: `http` (its own subdomain) and `space` (invoked on Space messages,
+ * like a Programmable Agent).
+ */
+
+type FunctionTriggerType = "keyword" | "regex" | "always";
+interface FunctionTrigger {
+    type: FunctionTriggerType;
+    /** Required for `keyword` (case-insensitive substring) and `regex`. */
+    pattern?: string;
+}
+interface FunctionTriggers {
+    /** HTTP-invocable at `<name>--<slug>.fns.<zone>`. */
+    http?: {
+        enabled: boolean;
+        methods?: string[];
+    };
+    /** Invoked on matching Space messages (per-Space opt-in via enable). */
+    space?: {
+        match: FunctionTrigger[];
+    };
+}
+interface FunctionCaps {
+    /** Per-invocation CPU ceiling (ms). */
+    cpuMs: number;
+    /** Per-invocation subrequest ceiling. */
+    subRequests: number;
+    /** Hard daily invocation cap (0 = unlimited). */
+    dailyInvocationBudget: number;
+}
+interface FunctionConfig {
+    functionId: string;
+    /** DNS-safe slug — the function's subdomain label + WfP script name part. */
+    name: string;
+    displayName: string;
+    triggers: FunctionTriggers;
+    /** Space ids this function is enabled on (per-Space opt-in for `space`). */
+    enabledSpaces: string[];
+    caps: FunctionCaps;
+    scriptName: string;
+    /** sha-256 of the last-deployed source. */
+    codeHash?: string;
+    /** When the source was last (re)deployed. */
+    deployedAt?: number;
+    createdAt: number;
+    updatedAt: number;
+}
+/** The editor-settable fields when deploying a function. */
+interface FunctionDeployInput {
+    name: string;
+    displayName: string;
+    /** Raw single-module ES worker source (`export default { fetch }`). */
+    code: string;
+    triggers?: FunctionTriggers;
+    caps?: Partial<FunctionCaps>;
+}
+/** Update input — any subset, including new `code` to redeploy. */
+type FunctionUpdateInput = Partial<FunctionDeployInput>;
+interface FunctionsNamespaceDeps {
+    http: HttpClient;
+}
+/** Common option: a management Space for delegated (non-owner) access. */
+interface FunctionScopeOpts {
+    space?: string;
+}
+declare class FunctionsNamespace {
+    private readonly deps;
+    constructor(deps: FunctionsNamespaceDeps);
+    /** List the app's functions. */
+    list(appId: string, opts?: FunctionScopeOpts): Promise<FunctionConfig[]>;
+    /** Read one function's config. */
+    get(appId: string, functionId: string, opts?: FunctionScopeOpts): Promise<{
+        config: FunctionConfig;
+    }>;
+    /** Read a function's decrypted source (owner/editor; for the editor UI). */
+    code(appId: string, functionId: string, opts?: FunctionScopeOpts): Promise<{
+        functionId: string;
+        code: string;
+        codeHash: string | null;
+    }>;
+    /** Deploy (create) a function (owner/editor only). */
+    deploy(appId: string, input: FunctionDeployInput, opts?: FunctionScopeOpts): Promise<{
+        config: FunctionConfig;
+    }>;
+    /** Update a function's editor-settable fields and/or redeploy its `code`. */
+    update(appId: string, functionId: string, patch: FunctionUpdateInput, opts?: FunctionScopeOpts): Promise<{
+        config: FunctionConfig;
+    }>;
+    /** Delete a function (owner/editor only). */
+    delete(appId: string, functionId: string, opts?: FunctionScopeOpts): Promise<{
+        deleted: boolean;
+    }>;
+    /** Enable the function on a Space (per-Space opt-in for the `space` trigger). */
+    enable(appId: string, functionId: string, spaceId: string, opts?: FunctionScopeOpts): Promise<{
+        config: FunctionConfig;
+    }>;
+    /** Disable the function on a Space. */
+    disable(appId: string, functionId: string, spaceId: string, opts?: FunctionScopeOpts): Promise<{
+        config: FunctionConfig;
+    }>;
+    private path;
+}
+
 /** The hosted Muhkoo Accelerator — the default {@link ClientOptions.baseUrl}. */
 declare const DEFAULT_BASE_URL = "https://api.muhkoo.dev";
 interface ClientOptions {
@@ -3188,6 +3487,10 @@ declare class Client {
     readonly message: MessageNamespace;
     /** Fan-out group spaces — `client.space.createSpace(...)`, etc. */
     readonly space: SpaceNamespace;
+    /** Programmable Agents — `client.agents.create(appId, …)`, etc. */
+    readonly agents: AgentsNamespace;
+    /** Serverless functions — `client.functions.deploy(appId, …)`, etc. */
+    readonly functions: FunctionsNamespace;
     private readonly session;
     private readonly http;
     /** Subscribers notified when a session expires and can't be recovered. */
@@ -3255,8 +3558,30 @@ declare class KeyringClient implements KeyringTransport {
         epoch: number;
     }>;
     invite(username: string): Promise<void>;
+    createInviteLink(opts?: {
+        expiresInSec?: number;
+        maxUses?: number;
+        role?: string;
+    }): Promise<InviteLink>;
+    listInviteLinks(): Promise<InviteLink[]>;
+    /** Set a member's role ("viewer" | "editor"). Owner-only on the server. */
+    setMemberRole(username: string, role: string): Promise<void>;
+    /** Roster with roles (owner/members only). */
+    members(): Promise<Array<{
+        memberId: string;
+        role: string;
+    }>>;
+    revokeInviteLink(token: string): Promise<void>;
+    /** Redeem a link: the server allowlists this member and asks the keeper to
+     *  wrap the group key for their identity. Caller must be authenticated. */
+    redeemInvite(req: {
+        token: string;
+        identityEcdhPub: string;
+        identityEcdsaPub?: string;
+        desiredEpoch?: number;
+    }): Promise<void>;
     fetchMetadata(): Promise<SpaceMetadata | null>;
 }
 
-export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, DEFAULT_BASE_URL, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, HashKnowledge, HttpClient, HttpError, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvNamespace, LocalStorageSessionStore, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, WSTransport, ZkAuth, buildCommitment, compilePrograms, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, manifestToStat, poseidonHash, quickVerify, randomBytes, shardHash, signMessage, toField, unwrapWithPassphrase, verify, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase };
-export type { ACL, ACLEntry, AuthClientOptions, AuthKeyPair, AuthSuccess, AuthToken, AuthType, AuthUser, Bn128WasmInstance, BroadcastChannelEvent, BroadcastChannelOptions, ChannelLike, ChunkKeyMaterial, ChunkManifest, CipherFrame, CipherMessage, CipherMessageHeader, CircuitBufferConfig, CircuitUrls, ClientOptions, DehydratedKeypair, DehydratedKeys, DoubleRatchetCipherDeps, ECDHCurve, EncodeResult, EphemeralEvent, EpochKeyProvider, FileManifest, FileNamespaceDeps, FileStat, FileStorageOptions, Groth16Proof, HttpClientOptions, IncomingFrame, KeyExchangeFrame, KeyPair, Keypair, KeyringClientDeps, KeyringTransport, KvNamespaceDeps, LoginOptions, MessageBody, MessageDeletedEvent, MessageEvent, MessageHeaders, MessageNamespaceDeps, MessageOptions, MessageSubscription, MuhkooMessageEvent, OAuthProvider, PacketCipher, PacketHeaders, PacketOptions, Participant, Permission, PermissionCheckRequest, PermissionCheckResult, PersonalSpaceClientOptions, PublicKeyJWK, RatchetState, ReceiveResult, RegisterParams, Role, SpaceDeps as RoomDeps, SpaceFileMetadata as RoomFileMetadata, SealedHeaders, Session, SessionOptions, SessionStore, SetOptions, ShardClientOptions, SharedSpaceClientOptions, SnarkProof, SpaceChannelLike, SpaceDeps, SpaceFileMetadata, SpaceKeyCache, SpaceKeyringDeps, SpaceMessageEvent, SpaceNamespaceDeps, StorageChangeEvent, StoredSession, Subscription, UserIdentity, VerificationKey, WSMessage, WSMessageType, WSTransportOptions, WrappedPayload, WriteFileInput, WriteFileOptions, WriteToShardsInput, ZkAuthDeps, ZkAuthenticateRequest, ZkChallengeResponse, ZkCompiled, ZkIdentity, ZkRegisterRequest, ZkRegisterResponse };
+export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, DEFAULT_BASE_URL, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HashKnowledge, HttpClient, HttpError, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvNamespace, LocalStorageSessionStore, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, WSTransport, ZkAuth, buildCommitment, compilePrograms, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, manifestToStat, poseidonHash, quickVerify, randomBytes, shardHash, signMessage, toField, unwrapWithPassphrase, verify, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase };
+export type { ACL, ACLEntry, AgentConfig, AgentCreateInput, AgentProvisioned, AgentScopeOpts, AgentSkill, AgentTrigger, AgentTriggerType, AgentUpdateInput, AgentsNamespaceDeps, AuthClientOptions, AuthKeyPair, AuthSuccess, AuthToken, AuthType, AuthUser, Bn128WasmInstance, BroadcastChannelEvent, BroadcastChannelOptions, ChannelLike, ChunkKeyMaterial, ChunkManifest, CipherFrame, CipherMessage, CipherMessageHeader, CircuitBufferConfig, CircuitUrls, ClientOptions, DehydratedKeypair, DehydratedKeys, DoubleRatchetCipherDeps, ECDHCurve, EncodeResult, EphemeralEvent, EpochKeyProvider, FileManifest, FileNamespaceDeps, FileStat, FileStorageOptions, FunctionCaps, FunctionConfig, FunctionDeployInput, FunctionScopeOpts, FunctionTrigger, FunctionTriggerType, FunctionTriggers, FunctionUpdateInput, FunctionsNamespaceDeps, Groth16Proof, HttpClientOptions, IncomingFrame, KeyExchangeFrame, KeyPair, Keypair, KeyringClientDeps, KeyringTransport, KvNamespaceDeps, LoginOptions, MessageBody, MessageDeletedEvent, MessageEvent, MessageHeaders, MessageNamespaceDeps, MessageOptions, MessageSubscription, MuhkooMessageEvent, OAuthProvider, PacketCipher, PacketHeaders, PacketOptions, Participant, Permission, PermissionCheckRequest, PermissionCheckResult, PersonalSpaceClientOptions, PublicKeyJWK, RatchetState, ReceiveResult, RegisterParams, Role, SpaceDeps as RoomDeps, SpaceFileMetadata as RoomFileMetadata, SealedHeaders, Session, SessionOptions, SessionStore, SetOptions, ShardClientOptions, SharedSpaceClientOptions, SnarkProof, SpaceChannelLike, SpaceDeps, SpaceFileMetadata, SpaceKeyCache, SpaceKeyringDeps, SpaceMessageEvent, SpaceNamespaceDeps, StorageChangeEvent, StoredSession, Subscription, UserIdentity, VerificationKey, WSMessage, WSMessageType, WSTransportOptions, WrappedPayload, WriteFileInput, WriteFileOptions, WriteToShardsInput, ZkAuthDeps, ZkAuthenticateRequest, ZkChallengeResponse, ZkCompiled, ZkIdentity, ZkRegisterRequest, ZkRegisterResponse };