@aglyn/tenant-data-admin 1.0.0-beta.220 → 1.0.0-beta.222

package/src/lib/server/organizations.d.ts

@@ -20,7 +20,7 @@
  * and the projections the security rules authorize against are never
  * client-writable (docs/MULTI_TENANT_FIRESTORE.md §8).
  */
-import { type ConsentGroup, type AglynOrganization, type AglynOrgBilling, type AglynOrgMember, type HostAccessRole, type OrgPermission, type OrgRole } from '@aglyn/aglyn/server';
+import { type ConsentGroup, type AglynOrganization, type AglynOrgBilling, type AglynOrgMember, type HostAccessRole, type OrgPermission, type OrgRole, type OwnerHandoffPreviousOwner } from '@aglyn/aglyn/server';
 import type { PluginActivityTargetType } from '@aglyn/aglyn/plugin-manager/plugin-activity-actions';
 import type { HostActivityActor } from '@aglyn/aglyn/app-utils/activity-presenter';
 export declare class OrgSlugTakenError extends Error {
@@ -102,6 +102,13 @@ export interface CreateOrganizationOptions {
      * nothing else.
      */
     bypassFreeWorkspaceCap?: boolean;
+    /**
+     * Whether the creator holds the `staff` claim, when the caller already
+     * knows (AGL-3466). Absent, it is looked up. A staff creator's owner row is
+     * stamped `staffSeat: true`, so a workspace staff build for a prospect
+     * leaves the prospect's one Free seat free for the prospect.
+     */
+    ownerStaffSeat?: boolean;
 }
 /**
  * Creates an org in one transaction: slug reservation (uniqueness), org
@@ -435,7 +442,7 @@ options?: {
 }): Promise<void>;
 /** What a host activity entry points at. Mirrors `HostActivityTarget`. */
 export interface HostActivityTarget {
-    type: 'host' | 'screen' | 'layout' | 'theme' | 'media' | 'content' | 'variable' | 'function' | 'workflow' | 'member' | 'component' | 'template' | 'contact' | 'company' | 'deal' | 'lead';
+    type: 'host' | 'screen' | 'layout' | 'theme' | 'media' | 'content' | 'variable' | 'function' | 'workflow' | 'member' | 'component' | 'template' | 'contact' | 'company' | 'deal' | 'lead' | PluginActivityTargetType;
     id?: string;
     name?: string;
     versionId?: string;
@@ -514,9 +521,11 @@ export declare function collaboratorSeatRefusal(options: {
     orgId: string;
     org: Partial<AglynOrgBilling>;
     hostIds: string[];
+    /** `staffSeat` admits platform staff without a seat (AGL-3466). */
     self?: {
         uid?: string | null;
         email?: string | null;
+        staffSeat?: boolean;
     };
 }): Promise<Response | null>;
 /**
@@ -566,9 +575,11 @@ export declare function managerSeatRefusal(options: {
     orgId: string;
     org: Partial<AglynOrgBilling>;
     becomesManager: boolean;
+    /** `staffSeat` admits platform staff without a seat (AGL-3466). */
     self?: {
         uid?: string | null;
         email?: string | null;
+        staffSeat?: boolean;
     };
 }): Promise<Response | null>;
 export interface UpsertOrgMemberOptions {
@@ -755,6 +766,95 @@ export declare function backfillMemberIdentityEverywhere(uid: string, identity:
  * sequence to keep it that way.
  */
 export declare function transferOrgOwnership(orgId: string, fromUid: string, toUid: string): Promise<void>;
+/**
+ * An owner handoff refused because it would need a team seat the plan does
+ * not have (AGL-3466).
+ *
+ * The loophole guard. A handoff reserves no seat, because the owner seat
+ * MOVES — but a `stay` handoff keeps the outgoing owner as an admin, so the
+ * workspace ends with one more manager than it started with. On Free that is
+ * a second manager on a one-seat plan, and without this check any owner could
+ * mint free managers by handing the workspace back and forth. The refusal
+ * names the way out: the outgoing owner leaving instead.
+ *
+ * Separate from {@link ManagerSeatLimitError} because the remedy is
+ * different, and a client that branches on `code` must be able to tell.
+ */
+export declare class OwnerHandoffSeatError extends Error {
+    readonly limit: number;
+    readonly upgradeRequired: boolean;
+    readonly previousOwner: OwnerHandoffPreviousOwner;
+    constructor(previousOwner: OwnerHandoffPreviousOwner, quota: {
+        limit: number;
+        upgradeRequired: boolean;
+    });
+}
+/**
+ * An owner handoff that can no longer be accepted as asked (AGL-3466): the
+ * invite was answered or withdrawn in the meantime, is not a handoff, is
+ * addressed to somebody else, or the accepter already owns the workspace.
+ */
+export declare class OwnerHandoffError extends Error {
+    readonly reason: 'not-pending' | 'not-handoff' | 'not-addressed' | 'already-owner';
+    constructor(reason: OwnerHandoffError['reason']);
+}
+/**
+ * Turn a handoff refusal into the response the invite route returns, or
+ * null when the error is something else and must keep propagating.
+ */
+export declare function ownerHandoffRefusalResponse(error: unknown): Response | null;
+/**
+ * The handoff seat check, asked when the invitation is SENT (AGL-3466), so
+ * nobody is mailed a handoff that will be refused when they click it.
+ *
+ * Not the enforcement — `acceptOwnerHandoff` asks again inside its
+ * transaction, against the account that actually accepts. Here the invitee
+ * is only an address, so their current seat is read off the roster row that
+ * carries it.
+ *
+ * @returns the 403 to send, or null to proceed.
+ */
+export declare function ownerHandoffSeatRefusal(options: {
+    orgId: string;
+    email: string;
+    previousOwner: OwnerHandoffPreviousOwner;
+    inviteeStaff: boolean;
+}): Promise<Response | null>;
+export interface AcceptOwnerHandoffOptions {
+    orgId: string;
+    inviteId: string;
+    /** The account accepting, which becomes the owner. */
+    uid: string;
+    /** The accepter's primary address, mirrored onto their roster row. */
+    email: string;
+    /**
+     * Every CONFIRMED address on the accepting account (AGL-2486). The invite
+     * must be addressed to one of them, re-checked inside the transaction.
+     */
+    emails: readonly string[];
+    displayName?: string;
+    photoURL?: string;
+}
+export interface AcceptOwnerHandoffResult {
+    previousOwnerUid: string;
+    previousOwner: OwnerHandoffPreviousOwner;
+}
+/**
+ * Accept an owner handoff (AGL-3466): the invitee becomes the owner, the
+ * outgoing owner stays on as an admin or leaves, and the invite is marked
+ * accepted — all in ONE transaction, with the seat check inside it.
+ *
+ * The move itself is {@link writeOwnershipMove}, the same writes a transfer
+ * makes. What this adds is what an invitation needs that a transfer does not:
+ * the incoming owner may not be on the roster yet, so their row is created
+ * with the identity a join would give it; and the outgoing owner may leave.
+ *
+ * The SSO lockout check is the CALLER's, for the reason
+ * `assessOwnershipTransferLockout` gives: it cannot live in this library
+ * without an import cycle, and `sso-transfer-lockout-wiring.spec.ts` pins
+ * that every caller of this asks it first.
+ */
+export declare function acceptOwnerHandoff(options: AcceptOwnerHandoffOptions): Promise<AcceptOwnerHandoffResult>;
 /**
  * Grants (or updates) per-host access for a uid without disturbing an
  * existing membership's org role or allHosts flag (AGL-238: the host user