@korajs/spaces 0.0.0-canary-20261014043637

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dr. Obed Ehoneah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,14 @@
+# @korajs/spaces
+
+Sharing for [Kora.js](https://github.com/ehoneahobed/kora) apps: email invitations, roles, members, leaving and transferring ownership, on top of access rules.
+
+```typescript
+import { spacesCollections } from '@korajs/spaces'            // schema fragment
+import { spacesRoutes, koraAuthIdentity } from '@korajs/spaces/server'
+import { createSpaces } from '@korajs/spaces/client'
+import { useMembers, useInvitations, useMyRole } from '@korajs/spaces/react'
+```
+
+Every action is one server transaction, so checks and writes commit together across concurrent requests and server instances. Members and pending invitations are synced data: readable offline, reactive.
+
+Guide: [Sharing](https://korajs.dev/guide/sharing).

package/dist/chunk-DZ4GBRUE.js

@@ -0,0 +1,148 @@
+// src/schema/spaces-collections.ts
+import { KoraError, memberOfKey, serverOnly, t } from "@korajs/core";
+var SPACE_MEMBERS = "space_members";
+var SPACE_INVITATIONS = "space_invitations";
+var SPACE_INVITATION_SECRETS = "space_invitation_secrets";
+var SpacesConfigError = class extends KoraError {
+  constructor(message, context) {
+    super(message, "SPACES_CONFIG_INVALID", context);
+    this.name = "SpacesConfigError";
+  }
+};
+function spacesCollections(config) {
+  const roles = [...config.roles];
+  if (roles.length < 2) {
+    throw new SpacesConfigError(
+      "spacesCollections needs at least two roles (a member role and the owner role).",
+      {
+        roles
+      }
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const role of roles) {
+    if (typeof role !== "string" || role.length === 0) {
+      throw new SpacesConfigError("Every role must be a non-empty string.", { roles });
+    }
+    if (seen.has(role)) throw new SpacesConfigError(`Role "${role}" is listed twice.`, { roles });
+    if (role === "leave") {
+      throw new SpacesConfigError(
+        '"leave" cannot be a role name: transfers use it to mean "no role".',
+        {
+          roles
+        }
+      );
+    }
+    seen.add(role);
+  }
+  const ownerRank = roles.indexOf(config.ownerRole);
+  const manageRank = roles.indexOf(config.manageRole);
+  if (ownerRank === -1) {
+    throw new SpacesConfigError(`ownerRole "${config.ownerRole}" is not one of the roles.`, {
+      roles
+    });
+  }
+  if (manageRank === -1) {
+    throw new SpacesConfigError(`manageRole "${config.manageRole}" is not one of the roles.`, {
+      roles
+    });
+  }
+  if (ownerRank !== roles.length - 1) {
+    throw new SpacesConfigError(
+      `ownerRole "${config.ownerRole}" must be the highest role (last in roles). Add an owner role above "${roles[roles.length - 1]}".`,
+      { roles, ownerRole: config.ownerRole }
+    );
+  }
+  if (manageRank >= ownerRank) {
+    throw new SpacesConfigError(
+      "manageRole must be below ownerRole: managers invite and manage members, and only the owner owns the space.",
+      { roles, ownerRole: config.ownerRole, manageRole: config.manageRole }
+    );
+  }
+  const groupEntries = Object.entries(config.groups);
+  if (groupEntries.length === 0) {
+    throw new SpacesConfigError("spacesCollections needs at least one group collection.");
+  }
+  const groups = {};
+  const accessGroups = {};
+  for (const [collection, group] of groupEntries) {
+    if (typeof group?.owner !== "string" || group.owner.length === 0) {
+      throw new SpacesConfigError(`Group collection "${collection}" needs its owner field.`, {
+        collection
+      });
+    }
+    if (collection === SPACE_MEMBERS || collection === SPACE_INVITATIONS || collection === SPACE_INVITATION_SECRETS) {
+      throw new SpacesConfigError(`"${collection}" is one of the kit's own collections.`, {
+        collection
+      });
+    }
+    groups[collection] = Object.freeze({ owner: group.owner });
+    accessGroups[collection] = { owner: group.owner, role: config.ownerRole };
+  }
+  const collections = {
+    space_members: {
+      fields: {
+        userId: t.string(),
+        group: t.string(),
+        role: t.string(),
+        invitedBy: t.string().optional(),
+        /** When the member accepted their invitation (server time). */
+        joinedAt: t.timestamp().optional(),
+        expiresAt: t.timestamp().optional()
+      },
+      indexes: ["group", "userId"],
+      // Members see who else is in their spaces. Only the server writes (no write rule).
+      access: { read: memberOfKey("group") }
+    },
+    space_invitations: {
+      fields: {
+        group: t.string(),
+        email: t.string(),
+        role: t.string(),
+        invitedBy: t.string(),
+        expiresAt: t.timestamp(),
+        createdAt: t.timestamp(),
+        tokenVersion: t.number()
+      },
+      indexes: ["group"],
+      // Invitee emails are visible to the space's managers only.
+      access: { read: memberOfKey("group", config.manageRole) }
+    },
+    space_invitation_secrets: {
+      fields: {
+        invitationId: t.string(),
+        group: t.string(),
+        tokenHash: t.string(),
+        tokenVersion: t.number(),
+        inviterId: t.string(),
+        authority: t.string(),
+        ownerVersion: t.string()
+      },
+      indexes: ["group", "inviterId"],
+      access: { read: serverOnly() }
+    }
+  };
+  const frozenRoles = Object.freeze(roles);
+  return Object.freeze({
+    roles: frozenRoles,
+    ownerRole: config.ownerRole,
+    manageRole: config.manageRole,
+    groups: Object.freeze(groups),
+    access: Object.freeze({
+      memberships: SPACE_MEMBERS,
+      roles: frozenRoles,
+      groups: accessGroups
+    }),
+    collections,
+    rank: (role) => frozenRoles.indexOf(role)
+  });
+}
+
+export {
+  SPACE_MEMBERS,
+  SPACE_INVITATIONS,
+  SPACE_INVITATION_SECRETS,
+  SpacesConfigError,
+  spacesCollections
+};
+//# sourceMappingURL=chunk-DZ4GBRUE.js.map

package/dist/chunk-DZ4GBRUE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema/spaces-collections.ts"],"sourcesContent":["import type { AccessConfigInput, CollectionInput } from '@korajs/core'\nimport { KoraError, memberOfKey, serverOnly, t } from '@korajs/core'\n\n/** The memberships collection the kit owns (`userId`, `group`, `role`, `invitedBy`). */\nexport const SPACE_MEMBERS = 'space_members'\n/** Pending invitations, readable by the group's managers. */\nexport const SPACE_INVITATIONS = 'space_invitations'\n/** Invitation token hashes and the inviter's authority. Never leaves the server. */\nexport const SPACE_INVITATION_SECRETS = 'space_invitation_secrets'\n\n/** A group collection shared through the kit: which field of its records holds the owner. */\nexport interface SpacesGroupConfig {\n\t/** The owner field, usually `t.string().stamp('userId')`. */\n\towner: string\n}\n\n/** Input of {@link spacesCollections}. */\nexport interface SpacesConfig<Role extends string = string, Group extends string = string> {\n\t/** Roles, lowest to highest. The owner role must be the highest. */\n\troles: readonly Role[]\n\t/** The role a group's owner holds, through the group record's owner field only. */\n\townerRole: Role\n\t/** The lowest role that may invite, change roles and remove members. Below `ownerRole`. */\n\tmanageRole: Role\n\t/** The collections whose records are shared spaces (a form, a document, a board). */\n\tgroups: Readonly<Record<Group, SpacesGroupConfig>>\n}\n\n/** The kit's three collections, ready to spread into `defineSchema({ collections })`. */\nexport interface SpacesCollectionsInput {\n\tspace_members: CollectionInput\n\tspace_invitations: CollectionInput\n\tspace_invitation_secrets: CollectionInput\n}\n\n/**\n * The result of {@link spacesCollections}: the schema parts, and the configuration the\n * server routes and React hooks read. Pass the same object to `spacesRoutes({ sharing })`.\n */\nexport interface Sharing<Role extends string = string, Group extends string = string> {\n\treadonly roles: readonly Role[]\n\treadonly ownerRole: Role\n\treadonly manageRole: Role\n\treadonly groups: Readonly<Record<Group, SpacesGroupConfig>>\n\t/** `defineSchema({ access })`. */\n\treadonly access: AccessConfigInput\n\t/** Spread into `defineSchema({ collections })`. */\n\treadonly collections: SpacesCollectionsInput\n\t/** The rank of `role` (0 = lowest), or -1 when it is not a role. */\n\trank(role: string): number\n}\n\n/** Thrown when `spacesCollections` is given a configuration it cannot share safely. */\nexport class SpacesConfigError extends KoraError {\n\tconstructor(message: string, context?: Record<string, unknown>) {\n\t\tsuper(message, 'SPACES_CONFIG_INVALID', context)\n\t\tthis.name = 'SpacesConfigError'\n\t}\n}\n\n/**\n * Declare sharing for one or more group collections: the access configuration (the\n * memberships collection, the roles, which collections are groups) and the kit's\n * collections (members, pending invitations, invitation secrets). Every membership and\n * invitation is written by the kit's server routes; clients read them as synced data.\n *\n * @param config - Roles (lowest to highest), the owner and manager roles, and the group collections\n * @returns The schema parts and the configuration to hand to `spacesRoutes`\n * @throws {SpacesConfigError} when the roles or groups cannot be shared safely\n *\n * @example\n * ```typescript\n * export const sharing = spacesCollections({\n *   roles: ['viewer', 'editor', 'admin', 'owner'],\n *   ownerRole: 'owner',\n *   manageRole: 'admin',\n *   groups: { forms: { owner: 'ownerId' } },\n * })\n *\n * export default defineSchema({\n *   version: 1,\n *   access: sharing.access,\n *   collections: { ...sharing.collections, forms: { ... } },\n * })\n * ```\n */\nexport function spacesCollections<const Role extends string, const Group extends string>(\n\tconfig: SpacesConfig<Role, Group>,\n): Sharing<Role, Group> {\n\tconst roles = [...config.roles]\n\tif (roles.length < 2) {\n\t\tthrow new SpacesConfigError(\n\t\t\t'spacesCollections needs at least two roles (a member role and the owner role).',\n\t\t\t{\n\t\t\t\troles,\n\t\t\t},\n\t\t)\n\t}\n\tconst seen = new Set<string>()\n\tfor (const role of roles) {\n\t\tif (typeof role !== 'string' || role.length === 0) {\n\t\t\tthrow new SpacesConfigError('Every role must be a non-empty string.', { roles })\n\t\t}\n\t\tif (seen.has(role)) throw new SpacesConfigError(`Role \"${role}\" is listed twice.`, { roles })\n\t\tif (role === 'leave') {\n\t\t\t// `transfer({ previousOwner: 'leave' })` means \"keep no role\".\n\t\t\tthrow new SpacesConfigError(\n\t\t\t\t'\"leave\" cannot be a role name: transfers use it to mean \"no role\".',\n\t\t\t\t{\n\t\t\t\t\troles,\n\t\t\t\t},\n\t\t\t)\n\t\t}\n\t\tseen.add(role)\n\t}\n\tconst ownerRank = roles.indexOf(config.ownerRole)\n\tconst manageRank = roles.indexOf(config.manageRole)\n\tif (ownerRank === -1) {\n\t\tthrow new SpacesConfigError(`ownerRole \"${config.ownerRole}\" is not one of the roles.`, {\n\t\t\troles,\n\t\t})\n\t}\n\tif (manageRank === -1) {\n\t\tthrow new SpacesConfigError(`manageRole \"${config.manageRole}\" is not one of the roles.`, {\n\t\t\troles,\n\t\t})\n\t}\n\t// Nobody may outrank the owner: the owner can act on every member, and the owner role is\n\t// held only through the group record's owner field (it moves only by transfer).\n\tif (ownerRank !== roles.length - 1) {\n\t\tthrow new SpacesConfigError(\n\t\t\t`ownerRole \"${config.ownerRole}\" must be the highest role (last in roles). Add an owner role above \"${roles[roles.length - 1]}\".`,\n\t\t\t{ roles, ownerRole: config.ownerRole },\n\t\t)\n\t}\n\tif (manageRank >= ownerRank) {\n\t\tthrow new SpacesConfigError(\n\t\t\t'manageRole must be below ownerRole: managers invite and manage members, and only the owner owns the space.',\n\t\t\t{ roles, ownerRole: config.ownerRole, manageRole: config.manageRole },\n\t\t)\n\t}\n\tconst groupEntries = Object.entries(config.groups) as Array<[Group, SpacesGroupConfig]>\n\tif (groupEntries.length === 0) {\n\t\tthrow new SpacesConfigError('spacesCollections needs at least one group collection.')\n\t}\n\tconst groups = {} as Record<Group, SpacesGroupConfig>\n\tconst accessGroups: Record<string, { owner: string; role: string }> = {}\n\tfor (const [collection, group] of groupEntries) {\n\t\tif (typeof group?.owner !== 'string' || group.owner.length === 0) {\n\t\t\tthrow new SpacesConfigError(`Group collection \"${collection}\" needs its owner field.`, {\n\t\t\t\tcollection,\n\t\t\t})\n\t\t}\n\t\tif (\n\t\t\tcollection === SPACE_MEMBERS ||\n\t\t\tcollection === SPACE_INVITATIONS ||\n\t\t\tcollection === SPACE_INVITATION_SECRETS\n\t\t) {\n\t\t\tthrow new SpacesConfigError(`\"${collection}\" is one of the kit's own collections.`, {\n\t\t\t\tcollection,\n\t\t\t})\n\t\t}\n\t\tgroups[collection] = Object.freeze({ owner: group.owner })\n\t\taccessGroups[collection] = { owner: group.owner, role: config.ownerRole }\n\t}\n\n\tconst collections: SpacesCollectionsInput = {\n\t\tspace_members: {\n\t\t\tfields: {\n\t\t\t\tuserId: t.string(),\n\t\t\t\tgroup: t.string(),\n\t\t\t\trole: t.string(),\n\t\t\t\tinvitedBy: t.string().optional(),\n\t\t\t\t/** When the member accepted their invitation (server time). */\n\t\t\t\tjoinedAt: t.timestamp().optional(),\n\t\t\t\texpiresAt: t.timestamp().optional(),\n\t\t\t},\n\t\t\tindexes: ['group', 'userId'],\n\t\t\t// Members see who else is in their spaces. Only the server writes (no write rule).\n\t\t\taccess: { read: memberOfKey('group') },\n\t\t},\n\t\tspace_invitations: {\n\t\t\tfields: {\n\t\t\t\tgroup: t.string(),\n\t\t\t\temail: t.string(),\n\t\t\t\trole: t.string(),\n\t\t\t\tinvitedBy: t.string(),\n\t\t\t\texpiresAt: t.timestamp(),\n\t\t\t\tcreatedAt: t.timestamp(),\n\t\t\t\ttokenVersion: t.number(),\n\t\t\t},\n\t\t\tindexes: ['group'],\n\t\t\t// Invitee emails are visible to the space's managers only.\n\t\t\taccess: { read: memberOfKey('group', config.manageRole) },\n\t\t},\n\t\tspace_invitation_secrets: {\n\t\t\tfields: {\n\t\t\t\tinvitationId: t.string(),\n\t\t\t\tgroup: t.string(),\n\t\t\t\ttokenHash: t.string(),\n\t\t\t\ttokenVersion: t.number(),\n\t\t\t\tinviterId: t.string(),\n\t\t\t\tauthority: t.string(),\n\t\t\t\townerVersion: t.string(),\n\t\t\t},\n\t\t\tindexes: ['group', 'inviterId'],\n\t\t\taccess: { read: serverOnly() },\n\t\t},\n\t}\n\n\tconst frozenRoles = Object.freeze(roles) as readonly Role[]\n\treturn Object.freeze({\n\t\troles: frozenRoles,\n\t\townerRole: config.ownerRole,\n\t\tmanageRole: config.manageRole,\n\t\tgroups: Object.freeze(groups),\n\t\taccess: Object.freeze({\n\t\t\tmemberships: SPACE_MEMBERS,\n\t\t\troles: frozenRoles,\n\t\t\tgroups: accessGroups,\n\t\t}),\n\t\tcollections,\n\t\trank: (role: string): number => frozenRoles.indexOf(role as Role),\n\t})\n}\n"],"mappings":"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","names":[]}

package/dist/client.cjs

@@ -0,0 +1,178 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client.ts
+var client_exports = {};
+__export(client_exports, {
+  SpacesError: () => SpacesError,
+  SpacesOfflineError: () => SpacesOfflineError,
+  createSpaces: () => createSpaces
+});
+module.exports = __toCommonJS(client_exports);
+
+// src/client/spaces-client.ts
+var import_core2 = require("@korajs/core");
+var import_internal = require("@korajs/core/internal");
+
+// src/schema/spaces-collections.ts
+var import_core = require("@korajs/core");
+var SPACE_MEMBERS = "space_members";
+var SpacesConfigError = class extends import_core.KoraError {
+  constructor(message, context) {
+    super(message, "SPACES_CONFIG_INVALID", context);
+    this.name = "SpacesConfigError";
+  }
+};
+
+// src/client/spaces-client.ts
+var SpacesError = class extends import_core2.KoraError {
+  constructor(spacesCode, message, status) {
+    super(message, spacesCode, { status });
+    this.spacesCode = spacesCode;
+    this.status = status;
+    this.name = "SpacesError";
+  }
+  spacesCode;
+  status;
+};
+var SpacesOfflineError = class extends SpacesError {
+  constructor(cause) {
+    super(
+      "OFFLINE",
+      "You are offline. Sharing changes need a connection; try again when you are back online.",
+      0
+    );
+    this.name = "SpacesOfflineError";
+    this.cause = cause;
+  }
+};
+var DEFAULT_ACCEPT_TIMEOUT_MS = 1e4;
+function createSpaces(app, options = {}) {
+  const path = `/${(options.basePath ?? "/api/spaces").replace(/^\/+|\/+$/g, "")}`;
+  if (path === "/") {
+    throw new SpacesConfigError(
+      'createSpaces needs a basePath below the root, such as "/api/spaces".',
+      {
+        basePath: options.basePath
+      }
+    );
+  }
+  const base = `${options.baseUrl?.replace(/\/+$/, "") ?? ""}${path}`;
+  const post = async (path2, body) => {
+    const doFetch = options.fetch ?? globalThis.fetch;
+    let response;
+    try {
+      response = await doFetch(`${base}${path2}`, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...await options.headers?.() },
+        body: JSON.stringify(body),
+        credentials: "same-origin",
+        referrerPolicy: "no-referrer"
+      });
+    } catch (error) {
+      throw new SpacesOfflineError(error);
+    }
+    let parsed = null;
+    try {
+      parsed = await response.json();
+    } catch {
+      parsed = null;
+    }
+    if (response.ok && (parsed === null || typeof parsed !== "object")) {
+      throw new SpacesOfflineError(new Error(`Unexpected response from ${path2}`));
+    }
+    if (!response.ok) {
+      const error = parsed?.error;
+      if (!error?.code) {
+        throw new SpacesOfflineError(new Error(`HTTP ${response.status}`));
+      }
+      throw new SpacesError(
+        error.code,
+        error.message ?? error.code,
+        response.status
+      );
+    }
+    return parsed;
+  };
+  const waitForMembership = (space, userId, joinedAt, timeoutMs) => new Promise((resolve) => {
+    const collection = app.collections[SPACE_MEMBERS];
+    if (!collection) {
+      resolve(false);
+      return;
+    }
+    let settled = false;
+    let unsubscribe = null;
+    const finish = (arrived) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      queueMicrotask(() => unsubscribe?.());
+      resolve(arrived);
+    };
+    const timer = setTimeout(() => finish(false), timeoutMs);
+    unsubscribe = collection.where({ group: (0, import_internal.groupKey)(space[0], space[1]), userId }).subscribe((rows) => {
+      if (rows.some((row) => row.joinedAt === joinedAt)) finish(true);
+    });
+    if (settled) unsubscribe();
+  });
+  return {
+    invite: (space, input) => post("/invitations/create", { space, email: input.email, role: input.role }),
+    async revokeInvitation(invitationId) {
+      await post("/invitations/revoke", { invitationId });
+    },
+    describe: (token) => post("/invitations/describe", { token }),
+    async accept(token, acceptOptions) {
+      const accepted = await post("/invitations/accept", { token });
+      const arrived = await waitForMembership(
+        accepted.space,
+        accepted.userId,
+        accepted.joinedAt,
+        acceptOptions?.timeoutMs ?? DEFAULT_ACCEPT_TIMEOUT_MS
+      );
+      return { ...accepted, pending: !arrived };
+    },
+    async decline(token) {
+      await post("/invitations/decline", { token });
+    },
+    changeRole: (space, userId, role, changeOptions) => post("/members/role", {
+      space,
+      userId,
+      role,
+      ...changeOptions?.from !== void 0 ? { from: changeOptions.from } : {}
+    }),
+    remove: (space, userId, removeOptions) => post("/members/remove", {
+      space,
+      userId,
+      ...removeOptions?.from !== void 0 ? { from: removeOptions.from } : {}
+    }),
+    leave: (space) => post("/leave", { space }),
+    transfer: (space, toUserId, transferOptions) => post("/transfer", {
+      space,
+      toUserId,
+      ...transferOptions?.previousOwner !== void 0 ? { previousOwner: transferOptions.previousOwner } : {}
+    })
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SpacesError,
+  SpacesOfflineError,
+  createSpaces
+});
+//# sourceMappingURL=client.cjs.map

package/dist/client.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts","../src/client/spaces-client.ts","../src/schema/spaces-collections.ts"],"sourcesContent":["// @korajs/spaces/client: the sharing actions, one request each.\n// Every export here is a public API commitment. Be explicit.\n\nexport { createSpaces, SpacesError, SpacesOfflineError } from './client/spaces-client'\nexport type {\n\tAcceptResult,\n\tSpacesAppLike,\n\tSpacesClient,\n\tSpacesClientOptions,\n} from './client/spaces-client'\n","import { KoraError } from '@korajs/core'\nimport { groupKey } from '@korajs/core/internal'\nimport type {\n\tAcceptInvitationResponse,\n\tCreateInvitationResponse,\n\tInvitationDescription,\n\tMemberChangeResponse,\n\tSpaceRef,\n\tSpacesErrorCode,\n} from '../protocol'\nimport { SPACE_MEMBERS, SpacesConfigError } from '../schema/spaces-collections'\n\n/** The parts of a Kora app the client reads: the local members collection. */\nexport interface SpacesAppLike {\n\tcollections: Readonly<\n\t\tRecord<\n\t\t\tstring,\n\t\t\t{\n\t\t\t\twhere(conditions: Record<string, unknown>): {\n\t\t\t\t\tsubscribe(callback: (rows: readonly Record<string, unknown>[]) => void): () => void\n\t\t\t\t}\n\t\t\t}\n\t\t>\n\t>\n}\n\n/** Options of {@link createSpaces}. */\nexport interface SpacesClientOptions {\n\t/** Where `spacesRoutes` is mounted (default `/api/spaces`). */\n\tbasePath?: string\n\t/** The server origin, when the routes are not on the page's own origin (`https://api.example.com`). */\n\tbaseUrl?: string\n\t/**\n\t * Headers for every request, usually the signed-in user's bearer token:\n\t * `headers: async () => ({ authorization: \\`Bearer ${await getAccessToken()}\\` })`.\n\t */\n\theaders?: () => Promise<Record<string, string>> | Record<string, string>\n\t/** A fetch implementation (default: the global `fetch`). */\n\tfetch?: typeof fetch\n}\n\n/** A refusal from the spaces routes. `code` is stable; `message` is for people. */\nexport class SpacesError extends KoraError {\n\tconstructor(\n\t\treadonly spacesCode: SpacesErrorCode | 'OFFLINE',\n\t\tmessage: string,\n\t\treadonly status: number,\n\t) {\n\t\tsuper(message, spacesCode, { status })\n\t\tthis.name = 'SpacesError'\n\t}\n}\n\n/**\n * The server could not be reached. Sharing changes are server decisions, so nothing is\n * queued: try again when online.\n */\nexport class SpacesOfflineError extends SpacesError {\n\tconstructor(cause: unknown) {\n\t\tsuper(\n\t\t\t'OFFLINE',\n\t\t\t'You are offline. Sharing changes need a connection; try again when you are back online.',\n\t\t\t0,\n\t\t)\n\t\tthis.name = 'SpacesOfflineError'\n\t\tthis.cause = cause\n\t}\n}\n\n/** Result of {@link SpacesClient.accept}. */\nexport interface AcceptResult extends AcceptInvitationResponse {\n\t/**\n\t * True when the membership is on the server but has not reached this device yet\n\t * (offline, or slower than `timeoutMs`). It arrives with the next sync.\n\t */\n\tpending: boolean\n}\n\n/** The sharing actions, each one request to the server. */\nexport interface SpacesClient {\n\t/** Invite `email` to `space` (or re-send their pending invitation with a new link). */\n\tinvite(space: SpaceRef, input: { email: string; role: string }): Promise<CreateInvitationResponse>\n\t/** Revoke a pending invitation. */\n\trevokeInvitation(invitationId: string): Promise<void>\n\t/** What the invitation behind `token` grants, for an accept page. */\n\tdescribe(token: string): Promise<InvitationDescription>\n\t/**\n\t * Accept the invitation behind `token`. Resolves once this device has the new\n\t * membership (so the space's data is on its way), or after `timeoutMs` (default 10 s)\n\t * with `pending: true`.\n\t */\n\taccept(token: string, options?: { timeoutMs?: number }): Promise<AcceptResult>\n\t/** Decline the invitation behind `token`. */\n\tdecline(token: string): Promise<void>\n\t/** Change a member's role. Pass `from` (the role you saw) to refuse if it changed meanwhile. */\n\tchangeRole(\n\t\tspace: SpaceRef,\n\t\tuserId: string,\n\t\trole: string,\n\t\toptions?: { from?: string },\n\t): Promise<MemberChangeResponse>\n\t/** Remove a member. */\n\tremove(\n\t\tspace: SpaceRef,\n\t\tuserId: string,\n\t\toptions?: { from?: string },\n\t): Promise<MemberChangeResponse>\n\t/** Leave a space (not the owner, who transfers it first). */\n\tleave(space: SpaceRef): Promise<MemberChangeResponse>\n\t/** Give the space to a member. You keep `previousOwner` (the manager role by default), or pass `'leave'`. */\n\ttransfer(\n\t\tspace: SpaceRef,\n\t\ttoUserId: string,\n\t\toptions?: { previousOwner?: string },\n\t): Promise<MemberChangeResponse>\n}\n\nconst DEFAULT_ACCEPT_TIMEOUT_MS = 10_000\n\n/**\n * The client of `spacesRoutes`.\n *\n * @param app - The Kora app (for `accept` to wait until the membership arrives)\n * @param options - Where the routes are and how to authenticate\n *\n * @example\n * ```typescript\n * const spaces = createSpaces(app, {\n *   headers: async () => ({ authorization: `Bearer ${await auth.getAccessToken()}` }),\n * })\n * await spaces.invite(['forms', formId], { email: 'bob@example.com', role: 'editor' })\n * ```\n */\nexport function createSpaces(app: SpacesAppLike, options: SpacesClientOptions = {}): SpacesClient {\n\t// One leading slash, no trailing one, so a relative `api/spaces` never resolves\n\t// against the current page.\n\tconst path = `/${(options.basePath ?? '/api/spaces').replace(/^\\/+|\\/+$/g, '')}`\n\tif (path === '/') {\n\t\t// `//invitations/create` would name another host (and send it the auth headers).\n\t\tthrow new SpacesConfigError(\n\t\t\t'createSpaces needs a basePath below the root, such as \"/api/spaces\".',\n\t\t\t{\n\t\t\t\tbasePath: options.basePath,\n\t\t\t},\n\t\t)\n\t}\n\tconst base = `${options.baseUrl?.replace(/\\/+$/, '') ?? ''}${path}`\n\n\tconst post = async <T>(path: string, body: unknown): Promise<T> => {\n\t\tconst doFetch = options.fetch ?? globalThis.fetch\n\t\tlet response: Response\n\t\ttry {\n\t\t\tresponse = await doFetch(`${base}${path}`, {\n\t\t\t\tmethod: 'POST',\n\t\t\t\theaders: { 'content-type': 'application/json', ...(await options.headers?.()) },\n\t\t\t\tbody: JSON.stringify(body),\n\t\t\t\tcredentials: 'same-origin',\n\t\t\t\treferrerPolicy: 'no-referrer',\n\t\t\t})\n\t\t} catch (error) {\n\t\t\tthrow new SpacesOfflineError(error)\n\t\t}\n\t\tlet parsed: unknown = null\n\t\ttry {\n\t\t\tparsed = await response.json()\n\t\t} catch {\n\t\t\tparsed = null\n\t\t}\n\t\tif (response.ok && (parsed === null || typeof parsed !== 'object')) {\n\t\t\t// A success that is not our JSON (a captive portal, a proxy page): not the server.\n\t\t\tthrow new SpacesOfflineError(new Error(`Unexpected response from ${path}`))\n\t\t}\n\t\tif (!response.ok) {\n\t\t\tconst error = (parsed as { error?: { code?: string; message?: string } } | null)?.error\n\t\t\tif (!error?.code) {\n\t\t\t\t// Not our routes answering (a proxy, a captive portal): treat as unreachable.\n\t\t\t\tthrow new SpacesOfflineError(new Error(`HTTP ${response.status}`))\n\t\t\t}\n\t\t\tthrow new SpacesError(\n\t\t\t\terror.code as SpacesErrorCode,\n\t\t\t\terror.message ?? error.code,\n\t\t\t\tresponse.status,\n\t\t\t)\n\t\t}\n\t\treturn parsed as T\n\t}\n\n\t/**\n\t * Resolve true once this membership's row (its `joinedAt`, written by the accept) is on\n\t * this device. A row left from an earlier membership never counts, even with the same\n\t * id and role.\n\t */\n\tconst waitForMembership = (\n\t\tspace: SpaceRef,\n\t\tuserId: string,\n\t\tjoinedAt: number,\n\t\ttimeoutMs: number,\n\t): Promise<boolean> =>\n\t\tnew Promise((resolve) => {\n\t\t\tconst collection = app.collections[SPACE_MEMBERS]\n\t\t\tif (!collection) {\n\t\t\t\tresolve(false)\n\t\t\t\treturn\n\t\t\t}\n\t\t\tlet settled = false\n\t\t\tlet unsubscribe: (() => void) | null = null\n\t\t\tconst finish = (arrived: boolean): void => {\n\t\t\t\tif (settled) return\n\t\t\t\tsettled = true\n\t\t\t\tclearTimeout(timer)\n\t\t\t\tqueueMicrotask(() => unsubscribe?.())\n\t\t\t\tresolve(arrived)\n\t\t\t}\n\t\t\tconst timer = setTimeout(() => finish(false), timeoutMs)\n\t\t\tunsubscribe = collection\n\t\t\t\t.where({ group: groupKey(space[0], space[1]), userId })\n\t\t\t\t.subscribe((rows) => {\n\t\t\t\t\tif (rows.some((row) => row.joinedAt === joinedAt)) finish(true)\n\t\t\t\t})\n\t\t\tif (settled) unsubscribe()\n\t\t})\n\n\treturn {\n\t\tinvite: (space, input) =>\n\t\t\tpost('/invitations/create', { space, email: input.email, role: input.role }),\n\t\tasync revokeInvitation(invitationId) {\n\t\t\tawait post('/invitations/revoke', { invitationId })\n\t\t},\n\t\tdescribe: (token) => post('/invitations/describe', { token }),\n\t\tasync accept(token, acceptOptions) {\n\t\t\tconst accepted = await post<AcceptInvitationResponse>('/invitations/accept', { token })\n\t\t\tconst arrived = await waitForMembership(\n\t\t\t\taccepted.space,\n\t\t\t\taccepted.userId,\n\t\t\t\taccepted.joinedAt,\n\t\t\t\tacceptOptions?.timeoutMs ?? DEFAULT_ACCEPT_TIMEOUT_MS,\n\t\t\t)\n\t\t\treturn { ...accepted, pending: !arrived }\n\t\t},\n\t\tasync decline(token) {\n\t\t\tawait post('/invitations/decline', { token })\n\t\t},\n\t\tchangeRole: (space, userId, role, changeOptions) =>\n\t\t\tpost('/members/role', {\n\t\t\t\tspace,\n\t\t\t\tuserId,\n\t\t\t\trole,\n\t\t\t\t...(changeOptions?.from !== undefined ? { from: changeOptions.from } : {}),\n\t\t\t}),\n\t\tremove: (space, userId, removeOptions) =>\n\t\t\tpost('/members/remove', {\n\t\t\t\tspace,\n\t\t\t\tuserId,\n\t\t\t\t...(removeOptions?.from !== undefined ? { from: removeOptions.from } : {}),\n\t\t\t}),\n\t\tleave: (space) => post('/leave', { space }),\n\t\ttransfer: (space, toUserId, transferOptions) =>\n\t\t\tpost('/transfer', {\n\t\t\t\tspace,\n\t\t\t\ttoUserId,\n\t\t\t\t...(transferOptions?.previousOwner !== undefined\n\t\t\t\t\t? { previousOwner: transferOptions.previousOwner }\n\t\t\t\t\t: {}),\n\t\t\t}),\n\t}\n}\n","import type { AccessConfigInput, CollectionInput } from '@korajs/core'\nimport { KoraError, memberOfKey, serverOnly, t } from '@korajs/core'\n\n/** The memberships collection the kit owns (`userId`, `group`, `role`, `invitedBy`). */\nexport const SPACE_MEMBERS = 'space_members'\n/** Pending invitations, readable by the group's managers. */\nexport const SPACE_INVITATIONS = 'space_invitations'\n/** Invitation token hashes and the inviter's authority. Never leaves the server. */\nexport const SPACE_INVITATION_SECRETS = 'space_invitation_secrets'\n\n/** A group collection shared through the kit: which field of its records holds the owner. */\nexport interface SpacesGroupConfig {\n\t/** The owner field, usually `t.string().stamp('userId')`. */\n\towner: string\n}\n\n/** Input of {@link spacesCollections}. */\nexport interface SpacesConfig<Role extends string = string, Group extends string = string> {\n\t/** Roles, lowest to highest. The owner role must be the highest. */\n\troles: readonly Role[]\n\t/** The role a group's owner holds, through the group record's owner field only. */\n\townerRole: Role\n\t/** The lowest role that may invite, change roles and remove members. Below `ownerRole`. */\n\tmanageRole: Role\n\t/** The collections whose records are shared spaces (a form, a document, a board). */\n\tgroups: Readonly<Record<Group, SpacesGroupConfig>>\n}\n\n/** The kit's three collections, ready to spread into `defineSchema({ collections })`. */\nexport interface SpacesCollectionsInput {\n\tspace_members: CollectionInput\n\tspace_invitations: CollectionInput\n\tspace_invitation_secrets: CollectionInput\n}\n\n/**\n * The result of {@link spacesCollections}: the schema parts, and the configuration the\n * server routes and React hooks read. Pass the same object to `spacesRoutes({ sharing })`.\n */\nexport interface Sharing<Role extends string = string, Group extends string = string> {\n\treadonly roles: readonly Role[]\n\treadonly ownerRole: Role\n\treadonly manageRole: Role\n\treadonly groups: Readonly<Record<Group, SpacesGroupConfig>>\n\t/** `defineSchema({ access })`. */\n\treadonly access: AccessConfigInput\n\t/** Spread into `defineSchema({ collections })`. */\n\treadonly collections: SpacesCollectionsInput\n\t/** The rank of `role` (0 = lowest), or -1 when it is not a role. */\n\trank(role: string): number\n}\n\n/** Thrown when `spacesCollections` is given a configuration it cannot share safely. */\nexport class SpacesConfigError extends KoraError {\n\tconstructor(message: string, context?: Record<string, unknown>) {\n\t\tsuper(message, 'SPACES_CONFIG_INVALID', context)\n\t\tthis.name = 'SpacesConfigError'\n\t}\n}\n\n/**\n * Declare sharing for one or more group collections: the access configuration (the\n * memberships collection, the roles, which collections are groups) and the kit's\n * collections (members, pending invitations, invitation secrets). Every membership and\n * invitation is written by the kit's server routes; clients read them as synced data.\n *\n * @param config - Roles (lowest to highest), the owner and manager roles, and the group collections\n * @returns The schema parts and the configuration to hand to `spacesRoutes`\n * @throws {SpacesConfigError} when the roles or groups cannot be shared safely\n *\n * @example\n * ```typescript\n * export const sharing = spacesCollections({\n *   roles: ['viewer', 'editor', 'admin', 'owner'],\n *   ownerRole: 'owner',\n *   manageRole: 'admin',\n *   groups: { forms: { owner: 'ownerId' } },\n * })\n *\n * export default defineSchema({\n *   version: 1,\n *   access: sharing.access,\n *   collections: { ...sharing.collections, forms: { ... } },\n * })\n * ```\n */\nexport function spacesCollections<const Role extends string, const Group extends string>(\n\tconfig: SpacesConfig<Role, Group>,\n): Sharing<Role, Group> {\n\tconst roles = [...config.roles]\n\tif (roles.length < 2) {\n\t\tthrow new SpacesConfigError(\n\t\t\t'spacesCollections needs at least two roles (a member role and the owner role).',\n\t\t\t{\n\t\t\t\troles,\n\t\t\t},\n\t\t)\n\t}\n\tconst seen = new Set<string>()\n\tfor (const role of roles) {\n\t\tif (typeof role !== 'string' || role.length === 0) {\n\t\t\tthrow new SpacesConfigError('Every role must be a non-empty string.', { roles })\n\t\t}\n\t\tif (seen.has(role)) throw new SpacesConfigError(`Role \"${role}\" is listed twice.`, { roles })\n\t\tif (role === 'leave') {\n\t\t\t// `transfer({ previousOwner: 'leave' })` means \"keep no role\".\n\t\t\tthrow new SpacesConfigError(\n\t\t\t\t'\"leave\" cannot be a role name: transfers use it to mean \"no role\".',\n\t\t\t\t{\n\t\t\t\t\troles,\n\t\t\t\t},\n\t\t\t)\n\t\t}\n\t\tseen.add(role)\n\t}\n\tconst ownerRank = roles.indexOf(config.ownerRole)\n\tconst manageRank = roles.indexOf(config.manageRole)\n\tif (ownerRank === -1) {\n\t\tthrow new SpacesConfigError(`ownerRole \"${config.ownerRole}\" is not one of the roles.`, {\n\t\t\troles,\n\t\t})\n\t}\n\tif (manageRank === -1) {\n\t\tthrow new SpacesConfigError(`manageRole \"${config.manageRole}\" is not one of the roles.`, {\n\t\t\troles,\n\t\t})\n\t}\n\t// Nobody may outrank the owner: the owner can act on every member, and the owner role is\n\t// held only through the group record's owner field (it moves only by transfer).\n\tif (ownerRank !== roles.length - 1) {\n\t\tthrow new SpacesConfigError(\n\t\t\t`ownerRole \"${config.ownerRole}\" must be the highest role (last in roles). Add an owner role above \"${roles[roles.length - 1]}\".`,\n\t\t\t{ roles, ownerRole: config.ownerRole },\n\t\t)\n\t}\n\tif (manageRank >= ownerRank) {\n\t\tthrow new SpacesConfigError(\n\t\t\t'manageRole must be below ownerRole: managers invite and manage members, and only the owner owns the space.',\n\t\t\t{ roles, ownerRole: config.ownerRole, manageRole: config.manageRole },\n\t\t)\n\t}\n\tconst groupEntries = Object.entries(config.groups) as Array<[Group, SpacesGroupConfig]>\n\tif (groupEntries.length === 0) {\n\t\tthrow new SpacesConfigError('spacesCollections needs at least one group collection.')\n\t}\n\tconst groups = {} as Record<Group, SpacesGroupConfig>\n\tconst accessGroups: Record<string, { owner: string; role: string }> = {}\n\tfor (const [collection, group] of groupEntries) {\n\t\tif (typeof group?.owner !== 'string' || group.owner.length === 0) {\n\t\t\tthrow new SpacesConfigError(`Group collection \"${collection}\" needs its owner field.`, {\n\t\t\t\tcollection,\n\t\t\t})\n\t\t}\n\t\tif (\n\t\t\tcollection === SPACE_MEMBERS ||\n\t\t\tcollection === SPACE_INVITATIONS ||\n\t\t\tcollection === SPACE_INVITATION_SECRETS\n\t\t) {\n\t\t\tthrow new SpacesConfigError(`\"${collection}\" is one of the kit's own collections.`, {\n\t\t\t\tcollection,\n\t\t\t})\n\t\t}\n\t\tgroups[collection] = Object.freeze({ owner: group.owner })\n\t\taccessGroups[collection] = { owner: group.owner, role: config.ownerRole }\n\t}\n\n\tconst collections: SpacesCollectionsInput = {\n\t\tspace_members: {\n\t\t\tfields: {\n\t\t\t\tuserId: t.string(),\n\t\t\t\tgroup: t.string(),\n\t\t\t\trole: t.string(),\n\t\t\t\tinvitedBy: t.string().optional(),\n\t\t\t\t/** When the member accepted their invitation (server time). */\n\t\t\t\tjoinedAt: t.timestamp().optional(),\n\t\t\t\texpiresAt: t.timestamp().optional(),\n\t\t\t},\n\t\t\tindexes: ['group', 'userId'],\n\t\t\t// Members see who else is in their spaces. Only the server writes (no write rule).\n\t\t\taccess: { read: memberOfKey('group') },\n\t\t},\n\t\tspace_invitations: {\n\t\t\tfields: {\n\t\t\t\tgroup: t.string(),\n\t\t\t\temail: t.string(),\n\t\t\t\trole: t.string(),\n\t\t\t\tinvitedBy: t.string(),\n\t\t\t\texpiresAt: t.timestamp(),\n\t\t\t\tcreatedAt: t.timestamp(),\n\t\t\t\ttokenVersion: t.number(),\n\t\t\t},\n\t\t\tindexes: ['group'],\n\t\t\t// Invitee emails are visible to the space's managers only.\n\t\t\taccess: { read: memberOfKey('group', config.manageRole) },\n\t\t},\n\t\tspace_invitation_secrets: {\n\t\t\tfields: {\n\t\t\t\tinvitationId: t.string(),\n\t\t\t\tgroup: t.string(),\n\t\t\t\ttokenHash: t.string(),\n\t\t\t\ttokenVersion: t.number(),\n\t\t\t\tinviterId: t.string(),\n\t\t\t\tauthority: t.string(),\n\t\t\t\townerVersion: t.string(),\n\t\t\t},\n\t\t\tindexes: ['group', 'inviterId'],\n\t\t\taccess: { read: serverOnly() },\n\t\t},\n\t}\n\n\tconst frozenRoles = Object.freeze(roles) as readonly Role[]\n\treturn Object.freeze({\n\t\troles: frozenRoles,\n\t\townerRole: config.ownerRole,\n\t\tmanageRole: config.manageRole,\n\t\tgroups: Object.freeze(groups),\n\t\taccess: Object.freeze({\n\t\t\tmemberships: SPACE_MEMBERS,\n\t\t\troles: frozenRoles,\n\t\t\tgroups: accessGroups,\n\t\t}),\n\t\tcollections,\n\t\trank: (role: string): number => frozenRoles.indexOf(role as Role),\n\t})\n}\n"],"mappings":"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","names":["import_core","path"]}

package/dist/client.d.cts

@@ -0,0 +1,99 @@
+import { KoraError } from '@korajs/core';
+import { A as AcceptInvitationResponse, S as SpaceRef, C as CreateInvitationResponse, I as InvitationDescription, M as MemberChangeResponse, a as SpacesErrorCode } from './protocol-DUU43t8s.cjs';
+
+/** The parts of a Kora app the client reads: the local members collection. */
+interface SpacesAppLike {
+    collections: Readonly<Record<string, {
+        where(conditions: Record<string, unknown>): {
+            subscribe(callback: (rows: readonly Record<string, unknown>[]) => void): () => void;
+        };
+    }>>;
+}
+/** Options of {@link createSpaces}. */
+interface SpacesClientOptions {
+    /** Where `spacesRoutes` is mounted (default `/api/spaces`). */
+    basePath?: string;
+    /** The server origin, when the routes are not on the page's own origin (`https://api.example.com`). */
+    baseUrl?: string;
+    /**
+     * Headers for every request, usually the signed-in user's bearer token:
+     * `headers: async () => ({ authorization: \`Bearer ${await getAccessToken()}\` })`.
+     */
+    headers?: () => Promise<Record<string, string>> | Record<string, string>;
+    /** A fetch implementation (default: the global `fetch`). */
+    fetch?: typeof fetch;
+}
+/** A refusal from the spaces routes. `code` is stable; `message` is for people. */
+declare class SpacesError extends KoraError {
+    readonly spacesCode: SpacesErrorCode | 'OFFLINE';
+    readonly status: number;
+    constructor(spacesCode: SpacesErrorCode | 'OFFLINE', message: string, status: number);
+}
+/**
+ * The server could not be reached. Sharing changes are server decisions, so nothing is
+ * queued: try again when online.
+ */
+declare class SpacesOfflineError extends SpacesError {
+    constructor(cause: unknown);
+}
+/** Result of {@link SpacesClient.accept}. */
+interface AcceptResult extends AcceptInvitationResponse {
+    /**
+     * True when the membership is on the server but has not reached this device yet
+     * (offline, or slower than `timeoutMs`). It arrives with the next sync.
+     */
+    pending: boolean;
+}
+/** The sharing actions, each one request to the server. */
+interface SpacesClient {
+    /** Invite `email` to `space` (or re-send their pending invitation with a new link). */
+    invite(space: SpaceRef, input: {
+        email: string;
+        role: string;
+    }): Promise<CreateInvitationResponse>;
+    /** Revoke a pending invitation. */
+    revokeInvitation(invitationId: string): Promise<void>;
+    /** What the invitation behind `token` grants, for an accept page. */
+    describe(token: string): Promise<InvitationDescription>;
+    /**
+     * Accept the invitation behind `token`. Resolves once this device has the new
+     * membership (so the space's data is on its way), or after `timeoutMs` (default 10 s)
+     * with `pending: true`.
+     */
+    accept(token: string, options?: {
+        timeoutMs?: number;
+    }): Promise<AcceptResult>;
+    /** Decline the invitation behind `token`. */
+    decline(token: string): Promise<void>;
+    /** Change a member's role. Pass `from` (the role you saw) to refuse if it changed meanwhile. */
+    changeRole(space: SpaceRef, userId: string, role: string, options?: {
+        from?: string;
+    }): Promise<MemberChangeResponse>;
+    /** Remove a member. */
+    remove(space: SpaceRef, userId: string, options?: {
+        from?: string;
+    }): Promise<MemberChangeResponse>;
+    /** Leave a space (not the owner, who transfers it first). */
+    leave(space: SpaceRef): Promise<MemberChangeResponse>;
+    /** Give the space to a member. You keep `previousOwner` (the manager role by default), or pass `'leave'`. */
+    transfer(space: SpaceRef, toUserId: string, options?: {
+        previousOwner?: string;
+    }): Promise<MemberChangeResponse>;
+}
+/**
+ * The client of `spacesRoutes`.
+ *
+ * @param app - The Kora app (for `accept` to wait until the membership arrives)
+ * @param options - Where the routes are and how to authenticate
+ *
+ * @example
+ * ```typescript
+ * const spaces = createSpaces(app, {
+ *   headers: async () => ({ authorization: `Bearer ${await auth.getAccessToken()}` }),
+ * })
+ * await spaces.invite(['forms', formId], { email: 'bob@example.com', role: 'editor' })
+ * ```
+ */
+declare function createSpaces(app: SpacesAppLike, options?: SpacesClientOptions): SpacesClient;
+
+export { type AcceptResult, type SpacesAppLike, type SpacesClient, type SpacesClientOptions, SpacesError, SpacesOfflineError, createSpaces };

package/dist/client.d.ts

@@ -0,0 +1,99 @@
+import { KoraError } from '@korajs/core';
+import { A as AcceptInvitationResponse, S as SpaceRef, C as CreateInvitationResponse, I as InvitationDescription, M as MemberChangeResponse, a as SpacesErrorCode } from './protocol-DUU43t8s.js';
+
+/** The parts of a Kora app the client reads: the local members collection. */
+interface SpacesAppLike {
+    collections: Readonly<Record<string, {
+        where(conditions: Record<string, unknown>): {
+            subscribe(callback: (rows: readonly Record<string, unknown>[]) => void): () => void;
+        };
+    }>>;
+}
+/** Options of {@link createSpaces}. */
+interface SpacesClientOptions {
+    /** Where `spacesRoutes` is mounted (default `/api/spaces`). */
+    basePath?: string;
+    /** The server origin, when the routes are not on the page's own origin (`https://api.example.com`). */
+    baseUrl?: string;
+    /**
+     * Headers for every request, usually the signed-in user's bearer token:
+     * `headers: async () => ({ authorization: \`Bearer ${await getAccessToken()}\` })`.
+     */
+    headers?: () => Promise<Record<string, string>> | Record<string, string>;
+    /** A fetch implementation (default: the global `fetch`). */
+    fetch?: typeof fetch;
+}
+/** A refusal from the spaces routes. `code` is stable; `message` is for people. */
+declare class SpacesError extends KoraError {
+    readonly spacesCode: SpacesErrorCode | 'OFFLINE';
+    readonly status: number;
+    constructor(spacesCode: SpacesErrorCode | 'OFFLINE', message: string, status: number);
+}
+/**
+ * The server could not be reached. Sharing changes are server decisions, so nothing is
+ * queued: try again when online.
+ */
+declare class SpacesOfflineError extends SpacesError {
+    constructor(cause: unknown);
+}
+/** Result of {@link SpacesClient.accept}. */
+interface AcceptResult extends AcceptInvitationResponse {
+    /**
+     * True when the membership is on the server but has not reached this device yet
+     * (offline, or slower than `timeoutMs`). It arrives with the next sync.
+     */
+    pending: boolean;
+}
+/** The sharing actions, each one request to the server. */
+interface SpacesClient {
+    /** Invite `email` to `space` (or re-send their pending invitation with a new link). */
+    invite(space: SpaceRef, input: {
+        email: string;
+        role: string;
+    }): Promise<CreateInvitationResponse>;
+    /** Revoke a pending invitation. */
+    revokeInvitation(invitationId: string): Promise<void>;
+    /** What the invitation behind `token` grants, for an accept page. */
+    describe(token: string): Promise<InvitationDescription>;
+    /**
+     * Accept the invitation behind `token`. Resolves once this device has the new
+     * membership (so the space's data is on its way), or after `timeoutMs` (default 10 s)
+     * with `pending: true`.
+     */
+    accept(token: string, options?: {
+        timeoutMs?: number;
+    }): Promise<AcceptResult>;
+    /** Decline the invitation behind `token`. */
+    decline(token: string): Promise<void>;
+    /** Change a member's role. Pass `from` (the role you saw) to refuse if it changed meanwhile. */
+    changeRole(space: SpaceRef, userId: string, role: string, options?: {
+        from?: string;
+    }): Promise<MemberChangeResponse>;
+    /** Remove a member. */
+    remove(space: SpaceRef, userId: string, options?: {
+        from?: string;
+    }): Promise<MemberChangeResponse>;
+    /** Leave a space (not the owner, who transfers it first). */
+    leave(space: SpaceRef): Promise<MemberChangeResponse>;
+    /** Give the space to a member. You keep `previousOwner` (the manager role by default), or pass `'leave'`. */
+    transfer(space: SpaceRef, toUserId: string, options?: {
+        previousOwner?: string;
+    }): Promise<MemberChangeResponse>;
+}
+/**
+ * The client of `spacesRoutes`.
+ *
+ * @param app - The Kora app (for `accept` to wait until the membership arrives)
+ * @param options - Where the routes are and how to authenticate
+ *
+ * @example
+ * ```typescript
+ * const spaces = createSpaces(app, {
+ *   headers: async () => ({ authorization: `Bearer ${await auth.getAccessToken()}` }),
+ * })
+ * await spaces.invite(['forms', formId], { email: 'bob@example.com', role: 'editor' })
+ * ```
+ */
+declare function createSpaces(app: SpacesAppLike, options?: SpacesClientOptions): SpacesClient;
+
+export { type AcceptResult, type SpacesAppLike, type SpacesClient, type SpacesClientOptions, SpacesError, SpacesOfflineError, createSpaces };