@peers-app/peers-sdk 0.23.14 → 0.24.0

package/dist/contracts/index.d.ts

@@ -12,6 +12,7 @@ export { PersistentContractRegistry } from "./persistent-registry";
 export { ContractRegistry, type IContractProviderRegistration } from "./registry";
 export { createRemoteContractEndpoint, getRemoteContractTransportFactory, type IRemoteContractHost, type IRemoteContractTarget, type RemoteContractTransportFactory, resolveRemoteTargetEndpoint, setRemoteContractTransportFactory, } from "./remote-contract-transport";
 export { DEVICE_OPERATIONS_CONTRACT_VERSION, DEVICE_OPERATIONS_MAX_QUERY_LENGTH, DEVICE_OPERATIONS_MAX_RESULT_BYTES, DEVICE_OPERATIONS_MAX_ROWS, DEVICE_OPERATIONS_MAX_TOOLS, type DeviceOperationCapability, deviceOperationsProviderPackageId, deviceOperationsToolIds, getDeviceOperationsContractDefinition, type IDeviceDatabaseQueryInput, type IDeviceDatabaseQueryResult, type IDeviceOperationStatus, type IDeviceToolListInput, type IDeviceToolLookupInput, type IDeviceToolLookupResult, type IDeviceToolRunInput, } from "./system/device-operations-contract";
+export { getInvitesContractDefinition, type IAcceptInviteResult, type ICreatedInvite, type IInvitePreview, type IInvitesConsumer, INVITES_CONTRACT_VERSION, } from "./system/invites-contract";
 export { getLogsContractDefinition, type ILogsConsumer, LOGS_CONTRACT_VERSION, resolveLogsContract, } from "./system/logs-contract";
 export * from "./system/network-contracts";
 export { getToolAccessControlContractDefinition, type IToolAccessControlConsumer, TOOL_ACCESS_CONTROL_CONTRACT_VERSION, } from "./system/tool-access-control-contract";

package/dist/contracts/index.js

@@ -15,7 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEVICE_OPERATIONS_MAX_TOOLS = exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = exports.setRemoteContractTransportFactory = exports.resolveRemoteTargetEndpoint = exports.getRemoteContractTransportFactory = exports.createRemoteContractEndpoint = exports.ContractRegistry = exports.PersistentContractRegistry = exports.waitForHostContractTransport = exports.subscribeHostContractTransport = exports.registerHostContractTransport = exports.getHostContractTransport = exports.setSchemaToFieldsFn = exports.extractToolShape = exports.extractTableShape = exports.createLocalContractConsumer = exports.contractsSchema = exports.contractsMetaData = exports.ContractsTable = exports.Contracts = exports.inProcessTransportPair = exports.connectionContractTransport = exports.CONTRACT_REQUEST_CHANNEL = exports.CONTRACT_NOTIFY_CHANNEL = exports.verifyRemoteContractIdentity = exports.registerContractResolver = exports.isSelfTrustedContractCaller = exports.handleContractCall = exports.getContractResolver = exports.createUserContextContractProviderRouter = exports.createLocalUserContextContractProviderRouter = exports.authorizeRemoteContractCall = exports.sameUserContractPermissionCheck = exports.createRemoteContractConsumer = exports.createContractProviderSession = exports.createContractProviderEndpoint = exports.createContractProvider = exports.createContractConsumer = exports.CONTRACT_CALL_RPC = exports.contractProvidersSchema = exports.contractProvidersMetaData = exports.ContractProvidersTable = exports.ContractProviders = exports.createContractProviderRouter = exports.PackageBuilder = exports.definePackage = exports.ContractBuilder = void 0;
-exports.validateProviderSatisfiesContract = exports.validateImmutability = exports.validateAlsoImplements = exports.contractKey = exports.registerSystemContract = exports.listSystemContracts = exports.installSystemContracts = exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = exports.getToolAccessControlContractDefinition = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = void 0;
+exports.validateProviderSatisfiesContract = exports.validateImmutability = exports.validateAlsoImplements = exports.contractKey = exports.registerSystemContract = exports.listSystemContracts = exports.installSystemContracts = exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = exports.getToolAccessControlContractDefinition = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.INVITES_CONTRACT_VERSION = exports.getInvitesContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = void 0;
 var builder_1 = require("./builder");
 Object.defineProperty(exports, "ContractBuilder", { enumerable: true, get: function () { return builder_1.ContractBuilder; } });
 Object.defineProperty(exports, "definePackage", { enumerable: true, get: function () { return builder_1.definePackage; } });
@@ -83,6 +83,9 @@ Object.defineProperty(exports, "DEVICE_OPERATIONS_MAX_TOOLS", { enumerable: true
 Object.defineProperty(exports, "deviceOperationsProviderPackageId", { enumerable: true, get: function () { return device_operations_contract_1.deviceOperationsProviderPackageId; } });
 Object.defineProperty(exports, "deviceOperationsToolIds", { enumerable: true, get: function () { return device_operations_contract_1.deviceOperationsToolIds; } });
 Object.defineProperty(exports, "getDeviceOperationsContractDefinition", { enumerable: true, get: function () { return device_operations_contract_1.getDeviceOperationsContractDefinition; } });
+var invites_contract_1 = require("./system/invites-contract");
+Object.defineProperty(exports, "getInvitesContractDefinition", { enumerable: true, get: function () { return invites_contract_1.getInvitesContractDefinition; } });
+Object.defineProperty(exports, "INVITES_CONTRACT_VERSION", { enumerable: true, get: function () { return invites_contract_1.INVITES_CONTRACT_VERSION; } });
 var logs_contract_1 = require("./system/logs-contract");
 Object.defineProperty(exports, "getLogsContractDefinition", { enumerable: true, get: function () { return logs_contract_1.getLogsContractDefinition; } });
 Object.defineProperty(exports, "LOGS_CONTRACT_VERSION", { enumerable: true, get: function () { return logs_contract_1.LOGS_CONTRACT_VERSION; } });

package/dist/contracts/system/index.d.ts

@@ -3,10 +3,12 @@
  * {@link registerSystemContract} side effect so the catalog is populated.
  */
 import "./device-operations-contract";
+import "./invites-contract";
 import "./logs-contract";
 import "./network-contracts";
 import "./tool-access-control-contract";
 export { DEVICE_OPERATIONS_CONTRACT_VERSION, DEVICE_OPERATIONS_MAX_QUERY_LENGTH, DEVICE_OPERATIONS_MAX_RESULT_BYTES, DEVICE_OPERATIONS_MAX_ROWS, DEVICE_OPERATIONS_MAX_TOOLS, type DeviceOperationCapability, deviceOperationsProviderPackageId, deviceOperationsToolIds, getDeviceOperationsContractDefinition, type IDeviceDatabaseQueryInput, type IDeviceDatabaseQueryResult, type IDeviceOperationStatus, type IDeviceToolListInput, type IDeviceToolLookupInput, type IDeviceToolLookupResult, type IDeviceToolRunInput, } from "./device-operations-contract";
+export { getInvitesContractDefinition, type IAcceptInviteResult, type ICreatedInvite, type IInvitePreview, type IInvitesConsumer, INVITES_CONTRACT_VERSION, } from "./invites-contract";
 export { getLogsContractDefinition, type ILogsConsumer, LOGS_CONTRACT_VERSION, resolveLogsContract, } from "./logs-contract";
 export * from "./network-contracts";
 export { getToolAccessControlContractDefinition, type IToolAccessControlConsumer, TOOL_ACCESS_CONTROL_CONTRACT_VERSION, } from "./tool-access-control-contract";

package/dist/contracts/system/index.js

@@ -14,12 +14,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = exports.getToolAccessControlContractDefinition = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = exports.DEVICE_OPERATIONS_MAX_TOOLS = exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = void 0;
+exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = exports.getToolAccessControlContractDefinition = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.INVITES_CONTRACT_VERSION = exports.getInvitesContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = exports.DEVICE_OPERATIONS_MAX_TOOLS = exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = void 0;
 /**
  * Built-in system contracts. Importing this barrel runs each module's
  * {@link registerSystemContract} side effect so the catalog is populated.
  */
 require("./device-operations-contract");
+require("./invites-contract");
 require("./logs-contract");
 require("./network-contracts");
 require("./tool-access-control-contract");
@@ -32,6 +33,9 @@ Object.defineProperty(exports, "DEVICE_OPERATIONS_MAX_TOOLS", { enumerable: true
 Object.defineProperty(exports, "deviceOperationsProviderPackageId", { enumerable: true, get: function () { return device_operations_contract_1.deviceOperationsProviderPackageId; } });
 Object.defineProperty(exports, "deviceOperationsToolIds", { enumerable: true, get: function () { return device_operations_contract_1.deviceOperationsToolIds; } });
 Object.defineProperty(exports, "getDeviceOperationsContractDefinition", { enumerable: true, get: function () { return device_operations_contract_1.getDeviceOperationsContractDefinition; } });
+var invites_contract_1 = require("./invites-contract");
+Object.defineProperty(exports, "getInvitesContractDefinition", { enumerable: true, get: function () { return invites_contract_1.getInvitesContractDefinition; } });
+Object.defineProperty(exports, "INVITES_CONTRACT_VERSION", { enumerable: true, get: function () { return invites_contract_1.INVITES_CONTRACT_VERSION; } });
 var logs_contract_1 = require("./logs-contract");
 Object.defineProperty(exports, "getLogsContractDefinition", { enumerable: true, get: function () { return logs_contract_1.getLogsContractDefinition; } });
 Object.defineProperty(exports, "LOGS_CONTRACT_VERSION", { enumerable: true, get: function () { return logs_contract_1.LOGS_CONTRACT_VERSION; } });

package/dist/contracts/system/invites-contract.d.ts

@@ -0,0 +1,121 @@
+import type { GroupMemberRole } from "../../data/group-member-roles";
+import type { IInvite, InviteStatus } from "../../data/invites";
+import type { GroupInviteMode, PeersInvite } from "../../invites/invite-token";
+import type { IContractConsumerBase } from "../contract-proxy";
+import type { IContractDefinition } from "../types";
+/** Version of the built-in System Invites contract. */
+export declare const INVITES_CONTRACT_VERSION = 1;
+/** A token the local user issued, with every encoding the UI and CLI need to share it. */
+export interface ICreatedInvite {
+    inviteId: string;
+    token: PeersInvite;
+    encoded: string;
+    url: string;
+    deepLink: string;
+}
+/** Verified, human-readable summary of a token before the user acts on it. */
+export interface IInvitePreview {
+    type: PeersInvite["type"];
+    inviter: PeersInvite["inviter"];
+    expiresAt: string;
+    expired: boolean;
+    /** Whether the inviter is already one of my contacts. */
+    knownContact: boolean;
+    group?: {
+        groupId: string;
+        name: string;
+        role: GroupMemberRole;
+        mode: GroupInviteMode;
+        /** Whether I am already a member of this group. */
+        alreadyMember: boolean;
+    };
+}
+/** Outcome of accepting a token or a pending inbound row. */
+export interface IAcceptInviteResult {
+    inviteId: string;
+    /** `accepted` when the local side is done; `pending` when waiting on the other party. */
+    status: InviteStatus;
+    /** Whether the reply or request has left this device (`sent`) or awaits connectivity. */
+    deliveryState?: "queued" | "sent";
+    groupId?: string;
+}
+/**
+ * Local-only host contract for issuing, accepting, and resolving contact and group invites.
+ *
+ * Remote device connections must not resolve this contract; UI and CLI reach it over the
+ * host transport. Pending state lives in the `Invites` table, which UIs subscribe to directly.
+ */
+export declare function getInvitesContractDefinition(): IContractDefinition;
+/** Consumer-side TypeScript shape for System Invites. */
+export interface IInvitesConsumer extends IContractConsumerBase {
+    tools: {
+        createContactInvite(input?: {
+            profile?: boolean;
+            expiresInMs?: number;
+        }): Promise<{
+            invite: ICreatedInvite;
+        }>;
+        createGroupInvite(input: {
+            groupId: string;
+            role?: GroupMemberRole;
+            mode?: GroupInviteMode;
+            expiresInMs?: number;
+            uses?: 1 | "unlimited";
+        }): Promise<{
+            invite: ICreatedInvite;
+        }>;
+        inviteContactToGroup(input: {
+            groupId: string;
+            userId: string;
+            role?: GroupMemberRole;
+        }): Promise<{
+            result: IAcceptInviteResult;
+        }>;
+        previewInvite(input: {
+            token: string;
+        }): Promise<{
+            preview: IInvitePreview;
+        }>;
+        acceptInvite(input: {
+            token?: string;
+            inviteId?: string;
+            trustLevel?: number;
+        }): Promise<{
+            result: IAcceptInviteResult;
+        }>;
+        declineInvite(input: {
+            inviteId: string;
+        }): Promise<{
+            result: IAcceptInviteResult;
+        }>;
+        approveJoinRequest(input: {
+            inviteId: string;
+            role?: GroupMemberRole;
+        }): Promise<{
+            result: IAcceptInviteResult;
+        }>;
+        denyJoinRequest(input: {
+            inviteId: string;
+        }): Promise<{
+            result: IAcceptInviteResult;
+        }>;
+        revokeInvite(input: {
+            inviteId: string;
+        }): Promise<{
+            result: IAcceptInviteResult;
+        }>;
+        regenerateProfileInvite(): Promise<{
+            invite: ICreatedInvite;
+        }>;
+        syncMailbox(): Promise<{
+            received: number;
+            sent: number;
+        }>;
+        listInvites(input?: {
+            status?: InviteStatus;
+            direction?: "in" | "out";
+        }): Promise<{
+            invites: IInvite[];
+        }>;
+    };
+}

package/dist/contracts/system/invites-contract.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INVITES_CONTRACT_VERSION = void 0;
+exports.getInvitesContractDefinition = getInvitesContractDefinition;
+const system_ids_1 = require("../../system-ids");
+const field_type_1 = require("../../types/field-type");
+const system_contracts_1 = require("../system-contracts");
+/** Version of the built-in System Invites contract. */
+exports.INVITES_CONTRACT_VERSION = 1;
+const field = (name, type, description, opts = {}) => ({ name, type, description, ...opts });
+let definition;
+/**
+ * Local-only host contract for issuing, accepting, and resolving contact and group invites.
+ *
+ * Remote device connections must not resolve this contract; UI and CLI reach it over the
+ * host transport. Pending state lives in the `Invites` table, which UIs subscribe to directly.
+ */
+function getInvitesContractDefinition() {
+    definition ??= {
+        contractId: system_ids_1.invitesContractId,
+        version: exports.INVITES_CONTRACT_VERSION,
+        devTag: "dev",
+        name: "System Invites",
+        description: "Issue, preview, accept, approve, and revoke contact and group invites.",
+        tables: [],
+        tools: [
+            {
+                name: "createContactInvite",
+                usageDescription: "Issue a signed contact token as a link, QR payload, and deep link.",
+                inputFields: [
+                    field("profile", field_type_1.FieldType.boolean, "Reusable profile QR (unlimited uses, 1 year).", {
+                        optional: true,
+                    }),
+                    field("expiresInMs", field_type_1.FieldType.number, "Lifetime override in milliseconds.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: [field("invite", field_type_1.FieldType.object, "The issued invite and encodings.")],
+            },
+            {
+                name: "createGroupInvite",
+                usageDescription: "Issue a signed group link token in approve or open mode.",
+                inputFields: [
+                    field("groupId", field_type_1.FieldType.id, "Group to invite into."),
+                    field("role", field_type_1.FieldType.number, "Role granted on join.", { optional: true }),
+                    field("mode", field_type_1.FieldType.string, "approve (default) or open.", { optional: true }),
+                    field("expiresInMs", field_type_1.FieldType.number, "Lifetime override in milliseconds.", {
+                        optional: true,
+                    }),
+                    field("uses", field_type_1.FieldType.string, "1 or unlimited (default unlimited).", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: [field("invite", field_type_1.FieldType.object, "The issued invite and encodings.")],
+            },
+            {
+                name: "inviteContactToGroup",
+                usageDescription: "Send a known contact a ready-to-accept group approval (no link).",
+                inputFields: [
+                    field("groupId", field_type_1.FieldType.id, "Group to invite into."),
+                    field("userId", field_type_1.FieldType.id, "Contact to invite."),
+                    field("role", field_type_1.FieldType.number, "Role granted on accept.", { optional: true }),
+                ],
+                outputFields: [field("result", field_type_1.FieldType.object, "Invite row id and delivery state.")],
+            },
+            {
+                name: "previewInvite",
+                usageDescription: "Verify a pasted or scanned token and describe it without acting.",
+                inputFields: [field("token", field_type_1.FieldType.string, "Token, invite URL, or peers:// link.")],
+                outputFields: [field("preview", field_type_1.FieldType.object, "Verified token summary.")],
+            },
+            {
+                name: "acceptInvite",
+                usageDescription: "Accept a token or a pending inbound invite row.",
+                inputFields: [
+                    field("token", field_type_1.FieldType.string, "Token text when accepting from paste/scan.", {
+                        optional: true,
+                    }),
+                    field("inviteId", field_type_1.FieldType.id, "Pending inbound row when accepting from the list.", {
+                        optional: true,
+                    }),
+                    field("trustLevel", field_type_1.FieldType.number, "Trust to assign the new contact.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: [field("result", field_type_1.FieldType.object, "Resulting row status.")],
+            },
+            {
+                name: "declineInvite",
+                usageDescription: "Decline a pending inbound invite.",
+                inputFields: [field("inviteId", field_type_1.FieldType.id, "Pending inbound row.")],
+                outputFields: [field("result", field_type_1.FieldType.object, "Resulting row status.")],
+            },
+            {
+                name: "approveJoinRequest",
+                usageDescription: "Approve a pending join request and send the group approval.",
+                inputFields: [
+                    field("inviteId", field_type_1.FieldType.id, "Pending inbound join request row."),
+                    field("role", field_type_1.FieldType.number, "Role override.", { optional: true }),
+                ],
+                outputFields: [field("result", field_type_1.FieldType.object, "Resulting row status.")],
+            },
+            {
+                name: "denyJoinRequest",
+                usageDescription: "Deny a pending join request.",
+                inputFields: [field("inviteId", field_type_1.FieldType.id, "Pending inbound join request row.")],
+                outputFields: [field("result", field_type_1.FieldType.object, "Resulting row status.")],
+            },
+            {
+                name: "revokeInvite",
+                usageDescription: "Revoke one of my outstanding invites.",
+                inputFields: [field("inviteId", field_type_1.FieldType.id, "Outbound row to revoke.")],
+                outputFields: [field("result", field_type_1.FieldType.object, "Resulting row status.")],
+            },
+            {
+                name: "regenerateProfileInvite",
+                usageDescription: "Bump my invite epoch (revoking all tokens) and issue a new profile QR.",
+                inputFields: [],
+                outputFields: [field("invite", field_type_1.FieldType.object, "The new profile invite.")],
+            },
+            {
+                name: "syncMailbox",
+                usageDescription: "Fetch and process queued mailbox messages, then retry queued sends.",
+                inputFields: [],
+                outputFields: [
+                    field("received", field_type_1.FieldType.number, "Messages processed."),
+                    field("sent", field_type_1.FieldType.number, "Queued sends delivered."),
+                ],
+            },
+            {
+                name: "listInvites",
+                usageDescription: "List invite rows, optionally filtered by status and direction.",
+                inputFields: [
+                    field("status", field_type_1.FieldType.string, "Row status filter.", { optional: true }),
+                    field("direction", field_type_1.FieldType.string, "in or out.", { optional: true }),
+                ],
+                outputFields: [field("invites", field_type_1.FieldType.object, "Invite rows.", { isArray: true })],
+            },
+        ],
+        observables: [],
+        events: [],
+    };
+    return definition;
+}
+(0, system_contracts_1.registerSystemContract)({
+    providerPackageId: system_ids_1.peersSystemPackageId,
+    contractId: system_ids_1.invitesContractId,
+    version: exports.INVITES_CONTRACT_VERSION,
+    getDefinition: getInvitesContractDefinition,
+});

package/dist/data/create-group.d.ts

@@ -0,0 +1,24 @@
+import type { UserContext } from "../context/user-context";
+import { type IGroup } from "./groups";
+/** Options for {@link createGroup}. */
+export interface CreateGroupInput {
+    /** Display name, 1–100 characters. */
+    name: string;
+    description?: string;
+    /** Bootstrap icon class, for example `bi-people-fill`. */
+    iconClassName?: string;
+    /** Use a specific id (tests); otherwise a new peer id is generated. */
+    groupId?: string;
+}
+/** Longest group name accepted by {@link createGroup}. */
+export declare const GROUP_NAME_MAX_LENGTH = 100;
+/**
+ * Create a group founded by the signed-in user: generate the group keypair, store its
+ * secret in the personal context, open the group data context, add the founder as a
+ * trusted member, and sign the `Groups` row into both the personal and group contexts.
+ *
+ * Runs on a host with signing enabled (`GroupsTable.enableGroupSigning`); UIs reach it
+ * through the host rather than duplicating the steps. Package seeding for the new context
+ * (for example `seedBundledPeersCore`) is the caller's responsibility.
+ */
+export declare function createGroup(userContext: UserContext, input: CreateGroupInput): Promise<IGroup>;

package/dist/data/create-group.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GROUP_NAME_MAX_LENGTH = void 0;
+exports.createGroup = createGroup;
+const socket_type_1 = require("../device/socket.type");
+const keys_1 = require("../keys");
+const utils_1 = require("../utils");
+const group_member_roles_1 = require("./group-member-roles");
+const group_members_1 = require("./group-members");
+const group_secret_1 = require("./group-secret");
+const groups_1 = require("./groups");
+const user_trust_levels_1 = require("./user-trust-levels");
+const users_1 = require("./users");
+/** Longest group name accepted by {@link createGroup}. */
+exports.GROUP_NAME_MAX_LENGTH = 100;
+/**
+ * Create a group founded by the signed-in user: generate the group keypair, store its
+ * secret in the personal context, open the group data context, add the founder as a
+ * trusted member, and sign the `Groups` row into both the personal and group contexts.
+ *
+ * Runs on a host with signing enabled (`GroupsTable.enableGroupSigning`); UIs reach it
+ * through the host rather than duplicating the steps. Package seeding for the new context
+ * (for example `seedBundledPeersCore`) is the caller's responsibility.
+ */
+async function createGroup(userContext, input) {
+    const name = input.name.trim();
+    if (!name)
+        throw new Error("Group name is required");
+    if (name.length > exports.GROUP_NAME_MAX_LENGTH) {
+        throw new Error(`Group name must be ${exports.GROUP_NAME_MAX_LENGTH} characters or less`);
+    }
+    const me = await userContext.getMe();
+    if (!me)
+        throw new Error("No signed-in user; cannot create a group");
+    const groupId = input.groupId ?? (0, utils_1.newid)();
+    const groupKeys = (0, keys_1.newKeys)();
+    const groupDataContext = userContext.getDataContext(groupId);
+    await (0, group_secret_1.saveGroupSecretKey)(userContext.userDataContext, groupId, groupKeys.secretKey, groupKeys);
+    await (0, users_1.Users)(groupDataContext).save(me);
+    await (0, user_trust_levels_1.setUserTrustLevel)(me.userId, socket_type_1.TrustLevel.Trusted, groupDataContext);
+    const group = await (0, groups_1.Groups)(userContext.userDataContext).signAndSave({
+        groupId,
+        name,
+        description: input.description?.trim() ?? "",
+        iconClassName: input.iconClassName?.trim() || "bi-people-fill",
+        founderUserId: me.userId,
+        disabled: false,
+        publicKey: groupKeys.publicKey,
+        publicBoxKey: groupKeys.publicBoxKey,
+        signature: "",
+    });
+    await (0, groups_1.Groups)(groupDataContext).signAndSave(group);
+    await (0, group_members_1.GroupMembers)(groupDataContext).signAndSave({
+        groupMemberId: (0, utils_1.newid)(),
+        groupId,
+        userId: me.userId,
+        role: group_member_roles_1.GroupMemberRole.Founder,
+        signature: "",
+    });
+    return group;
+}

package/dist/data/group-secret.d.ts

@@ -1,4 +1,5 @@
 import type { DataContext } from "../context/data-context";
+import type { UserContext } from "../context/user-context";
 import { type IPublicKeys, type IPublicPrivateKeys } from "../keys";
 import { type IPersistentVar } from "./persistent-vars";
 /** Prefix used for each group's encrypted secret-key persistent variable. */
@@ -11,6 +12,15 @@ export declare function groupSecretKeyPvarName(groupId: string): string;
  * @throws When the secret is malformed or derives different signing/box public keys.
  */
 export declare function validateGroupSecretKey(secretKey: string, expected: IPublicKeys): IPublicPrivateKeys;
+/**
+ * Read and validate a group's secret key from the user's personal context.
+ *
+ * The persistent variable is stored encrypted with the user's secret key; the decrypted
+ * value is checked against the signed group record before it is returned.
+ *
+ * @throws When the variable is missing, cannot be decrypted, or does not match the group.
+ */
+export declare function readGroupSecretKey(userContext: UserContext, groupId: string, userSecretKey: string): Promise<string>;
 /**
  * Save a known-valid group secret in the user's personal context.
  *

package/dist/data/group-secret.js

@@ -3,9 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GROUP_SECRET_KEY_PVAR_PREFIX = void 0;
 exports.groupSecretKeyPvarName = groupSecretKeyPvarName;
 exports.validateGroupSecretKey = validateGroupSecretKey;
+exports.readGroupSecretKey = readGroupSecretKey;
 exports.saveGroupSecretKey = saveGroupSecretKey;
 const keys_1 = require("../keys");
 const utils_1 = require("../utils");
+const groups_1 = require("./groups");
 const persistent_vars_1 = require("./persistent-vars");
 /** Prefix used for each group's encrypted secret-key persistent variable. */
 exports.GROUP_SECRET_KEY_PVAR_PREFIX = "groupSecretKey_";
@@ -25,6 +27,30 @@ function validateGroupSecretKey(secretKey, expected) {
     }
     return derived;
 }
+/**
+ * Read and validate a group's secret key from the user's personal context.
+ *
+ * The persistent variable is stored encrypted with the user's secret key; the decrypted
+ * value is checked against the signed group record before it is returned.
+ *
+ * @throws When the variable is missing, cannot be decrypted, or does not match the group.
+ */
+async function readGroupSecretKey(userContext, groupId, userSecretKey) {
+    const encrypted = await (0, persistent_vars_1.PersistentVars)(userContext.userDataContext).getPersistentVarValue(groupSecretKeyPvarName(groupId));
+    if (!encrypted) {
+        throw new Error(`Could not find secret key for group ${groupId}`);
+    }
+    const groupSecretKey = (0, keys_1.decryptData)(encrypted, userSecretKey);
+    if (!groupSecretKey || typeof groupSecretKey !== "string") {
+        throw new Error("Could not decrypt group secret key");
+    }
+    const group = await (0, groups_1.Groups)(userContext.userDataContext).get(groupId);
+    if (!group) {
+        throw new Error(`Could not find group record for group ${groupId}`);
+    }
+    validateGroupSecretKey(groupSecretKey, group);
+    return groupSecretKey;
+}
 /**
  * Save a known-valid group secret in the user's personal context.
  *

package/dist/data/group-share.d.ts

@@ -35,26 +35,6 @@ export declare function seedGroupContextFromShare(userContext: UserContext, grou
  * @returns boolean True if valid GroupShare structure
  */
 export declare function validateGroupShare(obj: any): obj is IGroupShare;
-/**
- * Estimates the size of a GroupShare object when serialized to JSON
- * @param groupShare The GroupShare object to estimate
- * @returns number Estimated size in characters
- */
-export declare function estimateGroupShareSize(groupShare: IGroupShare): number;
-/**
- * Checks if a GroupShare object would fit in a QR code of the specified version
- * @param groupShare The GroupShare object to check
- * @param qrVersion QR code version (10, 20, or 40)
- * @returns Object with size info and QR code compatibility
- */
-export declare function checkQRCodeCompatibility(groupShare: IGroupShare, qrVersion?: 10 | 20 | 40): {
-    size: number;
-    maxSize: number;
-    fits: boolean;
-    usagePercent: number;
-    qrVersion: 10 | 20 | 40;
-    memberCount: number;
-};
 /**
  * Copies text to clipboard with fallback handling
  * @param text Text to copy to clipboard

package/dist/data/group-share.js

@@ -3,8 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateGroupShare = generateGroupShare;
 exports.seedGroupContextFromShare = seedGroupContextFromShare;
 exports.validateGroupShare = validateGroupShare;
-exports.estimateGroupShareSize = estimateGroupShareSize;
-exports.checkQRCodeCompatibility = checkQRCodeCompatibility;
 exports.copyToClipboard = copyToClipboard;
 const __1 = require("..");
 const user_context_singleton_1 = require("../context/user-context-singleton");
@@ -144,39 +142,6 @@ function validateGroupShare(obj) {
     }
     return true;
 }
-/**
- * Estimates the size of a GroupShare object when serialized to JSON
- * @param groupShare The GroupShare object to estimate
- * @returns number Estimated size in characters
- */
-function estimateGroupShareSize(groupShare) {
-    return JSON.stringify(groupShare).length;
-}
-/**
- * Checks if a GroupShare object would fit in a QR code of the specified version
- * @param groupShare The GroupShare object to check
- * @param qrVersion QR code version (10, 20, or 40)
- * @returns Object with size info and QR code compatibility
- */
-function checkQRCodeCompatibility(groupShare, qrVersion = 20) {
-    const size = estimateGroupShareSize(groupShare);
-    const limits = {
-        10: 1273, // Version 10 limit
-        20: 3057, // Version 20 limit
-        40: 7089, // Version 40 limit
-    };
-    const maxSize = limits[qrVersion];
-    const fits = size <= maxSize;
-    const usagePercent = Math.round((size / maxSize) * 100);
-    return {
-        size,
-        maxSize,
-        fits,
-        usagePercent,
-        qrVersion,
-        memberCount: groupShare.groupMembers.length,
-    };
-}
 /**
  * Copies text to clipboard with fallback handling
  * @param text Text to copy to clipboard

package/dist/data/index.d.ts

@@ -2,6 +2,7 @@ export * from "./access-level";
 export * from "./assistants";
 export * from "./change-tracking";
 export * from "./channels";
+export * from "./create-group";
 export * from "./device-sync-info";
 export * from "./devices";
 export * from "./embeddings";
@@ -12,6 +13,7 @@ export * from "./group-permissions";
 export * from "./group-secret";
 export * from "./group-share";
 export * from "./groups";
+export * from "./invites";
 export * from "./messages";
 export * from "./package-table-identity";
 export * from "./package-version-resolver";

package/dist/data/index.js

@@ -18,6 +18,7 @@ __exportStar(require("./access-level"), exports);
 __exportStar(require("./assistants"), exports);
 __exportStar(require("./change-tracking"), exports);
 __exportStar(require("./channels"), exports);
+__exportStar(require("./create-group"), exports);
 __exportStar(require("./device-sync-info"), exports);
 __exportStar(require("./devices"), exports);
 __exportStar(require("./embeddings"), exports);
@@ -28,6 +29,7 @@ __exportStar(require("./group-permissions"), exports);
 __exportStar(require("./group-secret"), exports);
 __exportStar(require("./group-share"), exports);
 __exportStar(require("./groups"), exports);
+__exportStar(require("./invites"), exports);
 __exportStar(require("./messages"), exports);
 __exportStar(require("./package-table-identity"), exports);
 __exportStar(require("./package-version-resolver"), exports);