@spacefast/common 0.0.24 → 0.2.1

package/dist/contracts/access.d.ts

@@ -4,22 +4,20 @@ export declare const SPACE_ACCESS_PRESETS: readonly ["private", "team", "public"
 export declare const ACCESS_HANDOFF_MEDIA_TYPE = "application/vnd.spacefast.access-handoff+json";
 export declare const spaceAccessPresetSchema: z.ZodEnum<{
     team: "team";
-    public: "public";
     private: "private";
+    public: "public";
 }>;
 export type SpaceAccessPreset = z.infer<typeof spaceAccessPresetSchema>;
 /**
  * The sharing vocabulary. Capabilities are the ground truth; a role is a named
- * set of them, ordered from least to most. This is the only role enum and the
- * only role⇄capability mapping in the product — every surface (dashboard, CLI,
- * API, comments) names access with these four words and derives capabilities
- * here rather than keeping its own preset list.
+ * set of them, ordered from least to most. This is the product's only role enum
+ * and role⇄capability mapping: every surface derives its capabilities here.
  */
 export declare const ACCESS_ROLES: readonly ["viewer", "commenter", "editor", "manager"];
 export declare const accessRoleSchema: z.ZodEnum<{
+    editor: "editor";
     viewer: "viewer";
     commenter: "commenter";
-    editor: "editor";
     manager: "manager";
 }>;
 export type AccessRole = z.infer<typeof accessRoleSchema>;
@@ -31,15 +29,13 @@ export declare const ACCESS_ROLE_CAPABILITIES: {
 };
 export declare function accessRoleCapabilities(role: AccessRole): GrantCapability[];
 /**
- * The role a capability set amounts to, named by the strongest capability it
- * carries. A Grant assembled capability-by-capability need not match a role
- * exactly; this reports the role it reaches, never more.
+ * The role a capability set amounts to: the strongest role it reaches, never
+ * more. A Grant assembled capability-by-capability need not match one exactly.
  */
 export declare function accessRoleForCapabilities(capabilities: readonly GrantCapability[]): AccessRole;
 /**
- * Roles a credential-backed audience can carry. A Link or a password is a
- * secret anyone can forward, so it never publishes and never manages access —
- * the same boundary `grantSchema` enforces on the capabilities themselves.
+ * Roles a forwardable secret (a Link, a password) can carry. It never publishes
+ * and never manages access; `grantSchema` enforces that on capabilities too.
  */
 export declare const VISITOR_ACCESS_ROLES: readonly ["viewer", "commenter"];
 export type VisitorAccessRole = (typeof VISITOR_ACCESS_ROLES)[number];
@@ -70,18 +66,17 @@ export declare function accountPrincipal(userId: string): AccountPrincipal;
 /** The user id behind an account principal; null for anonymous or malformed. */
 export declare function accountPrincipalUserId(principal: string | undefined | null): string | null;
 /**
- * The identity an authority reference names on its own, if any. Credential
- * classes name nobody. This is the ONE place a class maps to an identity: at
- * the exchange that just authenticated it, never downstream.
+ * The identity an authority reference names on its own, if any. The ONE place a
+ * class maps to an identity: at the exchange that authenticated it, never after.
  */
 export declare function principalForAuthority(reference: AuthorityReference): IdentifiedPrincipal | undefined;
 export declare const personGrantSchema: z.ZodObject<{
     id: z.ZodString;
     scope: z.ZodString;
     role: z.ZodEnum<{
+        editor: "editor";
         viewer: "viewer";
         commenter: "commenter";
-        editor: "editor";
         manager: "manager";
     }>;
     target: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -120,9 +115,9 @@ export declare const spacePersonSchema: z.ZodObject<{
         id: z.ZodString;
         scope: z.ZodString;
         role: z.ZodEnum<{
+            editor: "editor";
             viewer: "viewer";
             commenter: "commenter";
-            editor: "editor";
             manager: "manager";
         }>;
         target: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -175,9 +170,9 @@ export declare const spacePeopleListSchema: z.ZodObject<{
             id: z.ZodString;
             scope: z.ZodString;
             role: z.ZodEnum<{
+                editor: "editor";
                 viewer: "viewer";
                 commenter: "commenter";
-                editor: "editor";
                 manager: "manager";
             }>;
             target: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -373,9 +368,9 @@ export declare const canonicalAccessRequestStatusSchema: z.ZodEnum<{
     denied: "denied";
 }>;
 export declare const accessRequestRoleSchema: z.ZodEnum<{
+    editor: "editor";
     viewer: "viewer";
     commenter: "commenter";
-    editor: "editor";
     manager: "manager";
 }>;
 export type AccessRequestRole = z.infer<typeof accessRequestRoleSchema>;
@@ -386,9 +381,9 @@ export declare const canonicalAccessRequestSchema: z.ZodObject<{
     email: z.ZodString;
     scope: z.ZodString;
     requestedRole: z.ZodEnum<{
+        editor: "editor";
         viewer: "viewer";
         commenter: "commenter";
-        editor: "editor";
         manager: "manager";
     }>;
     message: z.ZodNullable<z.ZodString>;
@@ -424,9 +419,9 @@ export type LinkCapabilities = z.infer<typeof linkCapabilitiesSchema>;
 export declare const personGrantWriteSchema: z.ZodObject<{
     scope: z.ZodString;
     role: z.ZodEnum<{
+        editor: "editor";
         viewer: "viewer";
         commenter: "commenter";
-        editor: "editor";
         manager: "manager";
     }>;
     target: z.ZodDefault<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -446,9 +441,9 @@ export declare const spacePersonInviteWriteSchema: z.ZodObject<{
     grants: z.ZodArray<z.ZodObject<{
         scope: z.ZodString;
         role: z.ZodEnum<{
+            editor: "editor";
             viewer: "viewer";
             commenter: "commenter";
-            editor: "editor";
             manager: "manager";
         }>;
         target: z.ZodDefault<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -469,9 +464,9 @@ export declare const spacePersonGrantSetWriteSchema: z.ZodObject<{
     grants: z.ZodArray<z.ZodObject<{
         scope: z.ZodString;
         role: z.ZodEnum<{
+            editor: "editor";
             viewer: "viewer";
             commenter: "commenter";
-            editor: "editor";
             manager: "manager";
         }>;
         target: z.ZodDefault<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -564,9 +559,9 @@ export declare const canonicalAccessRequestCreateSchema: z.ZodObject<{
     email: z.ZodString;
     scope: z.ZodString;
     requestedRole: z.ZodDefault<z.ZodEnum<{
+        editor: "editor";
         viewer: "viewer";
         commenter: "commenter";
-        editor: "editor";
         manager: "manager";
     }>>;
     message: z.ZodOptional<z.ZodString>;
@@ -574,9 +569,9 @@ export declare const canonicalAccessRequestCreateSchema: z.ZodObject<{
 export declare const canonicalAccessRequestApproveSchema: z.ZodObject<{
     scope: z.ZodOptional<z.ZodString>;
     role: z.ZodOptional<z.ZodEnum<{
+        editor: "editor";
         viewer: "viewer";
         commenter: "commenter";
-        editor: "editor";
         manager: "manager";
     }>>;
 }, z.core.$strip>;
@@ -617,23 +612,22 @@ export type PrivateOpen = z.infer<typeof privateOpenSchema>;
 export declare const teamSpaceAccessDefaultSchema: z.ZodObject<{
     newSpaceGrantPreset: z.ZodEnum<{
         team: "team";
-        public: "public";
         private: "private";
+        public: "public";
     }>;
 }, z.core.$strip>;
 export declare const teamSpaceAccessDefaultWriteSchema: z.ZodObject<{
     newSpaceGrantPreset: z.ZodEnum<{
         team: "team";
-        public: "public";
         private: "private";
+        public: "public";
     }>;
 }, z.core.$strip>;
 export declare const ACCESS_TOKEN_KID = "spacefast-runtime-v1";
 export declare const ACCESS_TOKEN_ALG = "EdDSA";
 /**
- * The claim-schema version every platform token carries in `v`. One signer,
- * one claim contract: a verifier that understands v1 refuses a token minted
- * under a later shape instead of reading unknown claims optimistically.
+ * The claim-schema version every platform token carries in `v`. A verifier that
+ * understands v1 refuses a token minted under a later shape.
  */
 export declare const PLATFORM_TOKEN_CLAIM_VERSION: 1;
 export declare const BLOB_GATE_DOWNLOAD_TTL_SECONDS: number;

package/dist/contracts/access.js

@@ -1,17 +1,12 @@
 import { z } from "zod";
 import { grantConstraintsPatchSchema, grantConstraintsSchema, grantResourceSetSchema, grantTargetSelectorSchema, } from "./grants.js";
-// ---------------------------------------------------------------------------
-// Canonical sharing model
-// ---------------------------------------------------------------------------
 export const SPACE_ACCESS_PRESETS = ["private", "team", "public"];
 export const ACCESS_HANDOFF_MEDIA_TYPE = "application/vnd.spacefast.access-handoff+json";
 export const spaceAccessPresetSchema = z.enum(SPACE_ACCESS_PRESETS);
 /**
  * The sharing vocabulary. Capabilities are the ground truth; a role is a named
- * set of them, ordered from least to most. This is the only role enum and the
- * only role⇄capability mapping in the product — every surface (dashboard, CLI,
- * API, comments) names access with these four words and derives capabilities
- * here rather than keeping its own preset list.
+ * set of them, ordered from least to most. This is the product's only role enum
+ * and role⇄capability mapping: every surface derives its capabilities here.
  */
 export const ACCESS_ROLES = ["viewer", "commenter", "editor", "manager"];
 export const accessRoleSchema = z.enum(ACCESS_ROLES);
@@ -25,9 +20,8 @@ export function accessRoleCapabilities(role) {
     return [...ACCESS_ROLE_CAPABILITIES[role]];
 }
 /**
- * The role a capability set amounts to, named by the strongest capability it
- * carries. A Grant assembled capability-by-capability need not match a role
- * exactly; this reports the role it reaches, never more.
+ * The role a capability set amounts to: the strongest role it reaches, never
+ * more. A Grant assembled capability-by-capability need not match one exactly.
  */
 export function accessRoleForCapabilities(capabilities) {
     if (capabilities.includes("access.manage"))
@@ -39,9 +33,8 @@ export function accessRoleForCapabilities(capabilities) {
     return "viewer";
 }
 /**
- * Roles a credential-backed audience can carry. A Link or a password is a
- * secret anyone can forward, so it never publishes and never manages access —
- * the same boundary `grantSchema` enforces on the capabilities themselves.
+ * Roles a forwardable secret (a Link, a password) can carry. It never publishes
+ * and never manages access; `grantSchema` enforces that on capabilities too.
  */
 export const VISITOR_ACCESS_ROLES = [
     "viewer",
@@ -137,16 +130,12 @@ export const authorityReferenceSchema = z
     .string()
     .regex(/^(member|person|link|password|machine|claim-preview|external):[A-Za-z0-9_.-]+$/);
 // WHO a session is, orthogonal to WHAT it may do. A session has exactly one
-// principal and any number of authorities; neither implies the other. A member
-// who arrives by share link is still that member, and a link authority alone
-// never makes someone anonymous.
+// principal and any number of authorities; neither implies the other.
 export const accountPrincipalSchema = z.string().regex(/^account:[A-Za-z0-9_-]+$/);
-// The three kinds of somebody. `account:` is a Spacefast user. `person:` is
-// someone this Space invited by email and who accepted — a real, named identity
-// with no platform account behind it. `external:` is a subject an identity
-// connection vouched for. Anything else — a share Link, a password, a machine
-// key, a claim preview — authenticates no one: those sessions stay anonymous
-// and carry the credential purely as an authority.
+// `person:` is someone this Space invited by email and who accepted, a named
+// identity with no platform account behind it. `external:` is a subject an
+// identity connection vouched for. Every other authority class (Link, password,
+// machine, claim preview) authenticates no one and leaves the session anonymous.
 export const identifiedPrincipalSchema = z
     .string()
     .regex(/^(?:account|person|external):[A-Za-z0-9_.-]+$/);
@@ -161,9 +150,8 @@ export function accountPrincipalUserId(principal) {
     return principal.slice("account:".length);
 }
 /**
- * The identity an authority reference names on its own, if any. Credential
- * classes name nobody. This is the ONE place a class maps to an identity: at
- * the exchange that just authenticated it, never downstream.
+ * The identity an authority reference names on its own, if any. The ONE place a
+ * class maps to an identity: at the exchange that authenticated it, never after.
  */
 export function principalForAuthority(reference) {
     return reference.startsWith("person:") || reference.startsWith("external:")
@@ -238,16 +226,14 @@ export const accessShareLinkSchema = z.object({
 export const accessShareLinkWithUrlSchema = accessShareLinkSchema.extend({
     url: z.string().url(),
 });
-// Reads re-derive the durable branded URL from the sealed token. Links minted
-// before branded URLs existed report null until the backfill mints theirs,
-// rather than pretending to hold a URL that would not open.
+// Reads re-derive the branded URL from the sealed token. Links minted before
+// branded URLs existed report null until the backfill mints theirs.
 export const accessShareLinkReadSchema = accessShareLinkSchema.extend({
     url: z.string().url().nullable(),
 });
-// The publish receipt exposes one durable access capability in both of its
-// useful transports: a browser entry URL and the raw token integrations send
-// in X-SF-Authorization. It is access to published bytes, never proof of
-// ownership; claim credentials stay a separate receipt field.
+// One durable access capability in both transports: a browser entry URL and the
+// raw token integrations send in X-SF-Authorization. It is access to published
+// bytes, never proof of ownership; claim credentials are a separate receipt field.
 export const publishedAccessSchema = z.object({
     url: z.string().url(),
     token: z.string().min(16).max(512),
@@ -292,8 +278,6 @@ export const linkCapabilitiesSchema = z
 export const personGrantWriteSchema = z.object({
     scope: accessScopePathSchema,
     role: accessRoleSchema,
-    // A Person can be invited to the live site, to one immutable Version, to a
-    // branch, or to every Version — the same selector Links and Grants take.
     target: grantTargetSelectorSchema.default({ kind: "live" }),
 });
 export const spacePersonInviteWriteSchema = z.object({
@@ -307,8 +291,6 @@ export const accessShareLinkCreateSchema = z.object({
     name: z.string().trim().min(1).max(200),
     landingPath: accessScopePathSchema.default("/"),
     resources: grantResourceSetSchema,
-    // Anonymous commenting is a product default: a Link that names no
-    // capabilities admits reading the page and leaving a comment.
     capabilities: linkCapabilitiesSchema.default(["page.view", "comments.read", "comments.write"]),
     constraints: grantConstraintsSchema.default({}),
     target: grantTargetSelectorSchema.default({ kind: "live" }),
@@ -353,27 +335,21 @@ export const teamSpaceAccessDefaultSchema = z.object({
 export const teamSpaceAccessDefaultWriteSchema = z.object({
     newSpaceGrantPreset: spaceAccessPresetSchema,
 });
-// ---------------------------------------------------------------------------
-// Unified visitor and collaboration tokens
-// ---------------------------------------------------------------------------
 export const ACCESS_TOKEN_KID = "spacefast-runtime-v1";
 export const ACCESS_TOKEN_ALG = "EdDSA";
 /**
- * The claim-schema version every platform token carries in `v`. One signer,
- * one claim contract: a verifier that understands v1 refuses a token minted
- * under a later shape instead of reading unknown claims optimistically.
+ * The claim-schema version every platform token carries in `v`. A verifier that
+ * understands v1 refuses a token minted under a later shape.
  */
 export const PLATFORM_TOKEN_CLAIM_VERSION = 1;
 export const BLOB_GATE_DOWNLOAD_TTL_SECONDS = 10 * 60;
 export const BLOB_GATE_SCAN_TTL_SECONDS = 60 * 60;
 export const BLOB_GATE_UPLOAD_TTL_SECONDS = 60 * 60;
 export const RUNTIME_JWKS_WELL_KNOWN_FILENAME = "spacefast-runtime-jwks.json";
-// Public identity attached only when a token consumer needs to render the
-// person behind an authority. Collaboration tickets carry this audience-bound
-// claim so Cast can paint an avatar without ever seeing an address: the
-// minting side normalizes a provider avatar or derives one from the email,
-// then drops the email. Raw email and provider-private profile metadata never
-// belong here.
+// Public identity, attached only when a consumer must render the person behind
+// an authority. The minting side normalizes a provider avatar or derives one
+// from the email, then drops the email. Raw email and provider-private profile
+// metadata never belong here.
 export const accessTokenPublicProfileSchema = z
     .object({
     name: z.string().min(1).max(120).optional(),
@@ -386,32 +362,25 @@ export const accessTokenPublicProfileSchema = z
     .strict();
 export const accessTokenPayloadSchema = z.object({
     // Typed purpose from the one platform signer. The runtime REQUIRES exactly
-    // this value before consuming the jti: a system-view token (or any other
-    // purpose signed by the same key) can never redeem into a visitor session,
-    // and a handoff can never pass a system-view check.
+    // this value before consuming the jti, so no other purpose signed by the same
+    // key can redeem into a visitor session.
     purpose: z.literal("handoff"),
-    // Claim-schema version stamped by the one signer.
     v: z.literal(PLATFORM_TOKEN_CLAIM_VERSION),
     sub: authorityReferenceSchema,
-    // Who this handoff authenticated, when it authenticated anybody. The account
-    // lane names the signed-in user; the invite and identity-connection lanes
-    // name the Person or external subject they just proved. Link, password,
-    // machine, and claim-preview lanes never set it, and its absence means the
-    // runtime session is anonymous. Identity comes from here alone — never
-    // inferred from the authority classes below.
+    // Who this handoff authenticated, when it authenticated anybody. Its absence
+    // means the runtime session is anonymous. Identity comes from here alone,
+    // never inferred from the authority classes below.
     principal: identifiedPrincipalSchema.optional(),
     authorities: z.array(authorityReferenceSchema).min(1).max(16),
     exp: z.number().int().nonnegative(),
     nbf: z.number().int().nonnegative(),
     iat: z.number().int().nonnegative(),
     iss: z.string().min(1),
-    // The Space this handoff belongs to, and the token's identity: a Space keeps
-    // its id across claim, rename, and every custom domain it later answers on,
-    // so the audience is stable where a serving host is not.
+    // The Space this handoff belongs to. A Space keeps its id across claim,
+    // rename, and custom domains, so the audience is stable where a host is not.
     aud: z.string().min(1),
-    // The lowercased serving host the handoff was minted for. Host binding did
-    // not go away when `aud` stopped carrying it — it lives here, and the runtime
-    // rejects a token presented on any other host.
+    // The lowercased serving host the handoff was minted for. The runtime rejects
+    // a token presented on any other host.
     host: z.string().min(1),
     spaceId: z.string().min(1),
     // Shared opaque identity for the runtime session and its access-origin

package/dist/contracts/activity.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-export declare const ACTIVITY_EVENT_CODES: readonly ["space.created", "space.claimed", "feedback.lead_claim_pending", "space.transferred", "space.expired", "space.disabled", "space.enabled", "space.deleted", "space.config_updated", "space.slug_updated", "site.provision_requested", "site.placement_hold_set", "site.placement_hold_cleared", "site.burst_toggled", "space.access_logout_all", "space.access_transfer_scrub", "space.share_link_created", "space.share_link_revoked", "space.access_request_created", "space.access_request_resolved", "space.grant_created", "space.grant_updated", "space.grant_revoked", "team.access_defaults_updated", "version.created", "version.ready", "version.warning", "version.failed", "version.expired", "version.canceled", "version.deleted", "channel.promoted", "build.created", "build.succeeded", "build.failed", "build.canceled", "build.skipped", "domain.created", "domain.verified", "domain.verification_failed", "domain.control_lost", "domain.dns_updated", "domain.nameservers_updated", "domain.registration_purchased", "domain.registration_renewed", "domain.registration_expiring", "domain.registration_expired", "domain.transfer_in_started", "domain.transfer_out_started", "domain.deleted", "domain.attached", "domain.activated", "domain.blocked", "domain.detached", "transfer.requested", "transfer.confirmed", "transfer.completed", "transfer.canceled", "transfer.expired", "transfer.failed", "variable.updated", "variable.deleted", "api_key.created", "api_key.updated", "api_key.revoked", "agent_handoff.created", "agent_handoff.redeemed", "agent_handoff.revoked", "webhook.created", "webhook.updated", "webhook.secret_rotated", "webhook.disabled", "webhook.deleted", "team.updated", "team.slug_updated", "team.member_added", "team.member_removed", "team.member_role_updated", "team.builds_deploys_quota_exceeded", "tenant.past_due", "tenant.suspended", "tenant.reactivated", "tenant.deleted", "comment.token_minted", "comment.created", "comment.reply_created", "comment.archived", "comment.unarchived", "abuse_report.created", "abuse_report.updated", "claim.blocked_takedown", "claim.authority_rotated", "user.created", "user.signed_in", "user.deleted", "user.impersonation_started", "user.impersonation_stopped", "user.two_factor_enabled", "user.two_factor_disabled"];
+export declare const ACTIVITY_EVENT_CODES: readonly ["space.created", "space.claimed", "feedback.lead_claim_pending", "space.transferred", "space.expired", "space.disabled", "space.enabled", "space.deleted", "space.config_updated", "space.slug_updated", "site.provision_requested", "site.burst_toggled", "space.access_logout_all", "space.access_transfer_scrub", "space.share_link_created", "space.share_link_revoked", "space.access_request_created", "space.access_request_resolved", "space.grant_created", "space.grant_updated", "space.grant_revoked", "team.access_defaults_updated", "version.created", "version.ready", "version.warning", "version.failed", "version.expired", "version.canceled", "version.deleted", "channel.promoted", "build.created", "build.succeeded", "build.failed", "build.canceled", "build.skipped", "domain.created", "domain.verified", "domain.verification_failed", "domain.control_lost", "domain.dns_updated", "domain.nameservers_updated", "domain.registration_purchased", "domain.registration_renewed", "domain.registration_expiring", "domain.registration_expired", "domain.transfer_in_started", "domain.transfer_out_started", "domain.deleted", "domain.attached", "domain.activated", "domain.blocked", "domain.detached", "transfer.requested", "transfer.confirmed", "transfer.completed", "transfer.canceled", "transfer.expired", "transfer.failed", "cron.failed", "variable.updated", "variable.deleted", "api_key.created", "api_key.updated", "api_key.revoked", "agent_handoff.created", "agent_handoff.redeemed", "agent_handoff.revoked", "webhook.created", "webhook.updated", "webhook.secret_rotated", "webhook.disabled", "webhook.deleted", "team.updated", "team.slug_updated", "team.member_added", "team.member_removed", "team.member_role_updated", "team.builds_deploys_quota_exceeded", "tenant.past_due", "tenant.suspended", "tenant.reactivated", "tenant.deleted", "principal.plan_reset", "principal.space_quota_exceeded", "principal.suspended", "principal.unsuspended", "principal.closed", "usage.threshold_crossed", "usage.period_finalized", "usage.corrected", "principal.notification.claim", "principal.notification.space_expiry", "principal.notification.access_invitation", "principal.notification.access_request", "principal.notification.access_verification", "principal.notification.publish_receipt", "principal.notification.comment", "comment.token_minted", "comment.created", "comment.reply_created", "comment.archived", "comment.unarchived", "abuse_report.created", "abuse_report.updated", "claim.blocked_takedown", "claim.authority_rotated", "user.created", "user.signed_in", "user.deleted", "user.impersonation_started", "user.impersonation_stopped", "user.two_factor_enabled", "user.two_factor_disabled", "user.password_set", "user.password_changed", "user.provider_linked", "user.provider_unlinked", "user.email_added", "user.email_removed", "user.primary_email_changed", "user.superadmin_granted", "user.superadmin_revoked", "user.privacy_updated", "user.deletion_requested", "user.deletion_completed"];
 export type ActivityEventCode = (typeof ACTIVITY_EVENT_CODES)[number];
 export declare function isActivityEventCode(value: string): value is ActivityEventCode;
 export declare function isValidActivityEventFilter(filter: string): boolean;
@@ -10,6 +10,9 @@ export declare const activityActorSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"api_key">;
     id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"partner_token">;
+    id: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"oauth_client">;
     id: z.ZodString;
@@ -32,6 +35,10 @@ export declare const activityEventSchema: z.ZodObject<{
     id: z.ZodString;
     sequence: z.ZodNumber;
     tenantId: z.ZodString;
+    mode: z.ZodEnum<{
+        live: "live";
+        test: "test";
+    }>;
     principal: z.ZodNullable<z.ZodObject<{
         tenantId: z.ZodString;
         principalType: z.ZodEnum<{
@@ -47,6 +54,9 @@ export declare const activityEventSchema: z.ZodObject<{
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"api_key">;
         id: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"partner_token">;
+        id: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"oauth_client">;
         id: z.ZodString;
@@ -80,6 +90,10 @@ export declare const activityListResponseSchema: z.ZodObject<{
         id: z.ZodString;
         sequence: z.ZodNumber;
         tenantId: z.ZodString;
+        mode: z.ZodEnum<{
+            live: "live";
+            test: "test";
+        }>;
         principal: z.ZodNullable<z.ZodObject<{
             tenantId: z.ZodString;
             principalType: z.ZodEnum<{
@@ -95,6 +109,9 @@ export declare const activityListResponseSchema: z.ZodObject<{
         }, z.core.$strip>, z.ZodObject<{
             type: z.ZodLiteral<"api_key">;
             id: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"partner_token">;
+            id: z.ZodString;
         }, z.core.$strip>, z.ZodObject<{
             type: z.ZodLiteral<"oauth_client">;
             id: z.ZodString;

package/dist/contracts/activity.js

@@ -1,10 +1,10 @@
 import { z } from "zod";
 import { AnyObjectSchema, CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
-// The single event taxonomy (internal-docs/platform.md "Event taxonomy").
-// Every emitted activity event and every webhook `events` filter selects on
-// these codes.
-// `appendActivityEvent` is typed against this list, so emitting a code that is
-// not in the table is a typecheck (CI) failure.
+import { tenantMode } from "./enums.js";
+import { PRINCIPAL_NOTIFICATION_EVENT_CODES } from "./partner-notifications.js";
+// The single event taxonomy (the platform spec "Event taxonomy"). Every emitted
+// event and every webhook `events` filter selects on these codes, and
+// `appendActivityEvent` is typed against the list, so an off-list code fails CI.
 export const ACTIVITY_EVENT_CODES = [
     // space
     "space.created",
@@ -19,8 +19,6 @@ export const ACTIVITY_EVENT_CODES = [
     "space.slug_updated",
     // site
     "site.provision_requested",
-    "site.placement_hold_set",
-    "site.placement_hold_cleared",
     "site.burst_toggled",
     // access
     "space.access_logout_all",
@@ -75,6 +73,8 @@ export const ACTIVITY_EVENT_CODES = [
     "transfer.canceled",
     "transfer.expired",
     "transfer.failed",
+    // cron (only failures are reported; a run that succeeds is silent)
+    "cron.failed",
     // variable (key-level only; never values)
     "variable.updated",
     "variable.deleted",
@@ -92,38 +92,59 @@ export const ACTIVITY_EVENT_CODES = [
     "webhook.secret_rotated",
     "webhook.disabled",
     "webhook.deleted",
-    // team (builds_deploys_quota_exceeded is a shipped additive extension: the
-    // pooled monthly builds+deploys meter is SOFT — it tracks, never blocks)
+    // team (the pooled monthly builds+deploys meter is SOFT: it tracks, never blocks)
     "team.updated",
     "team.slug_updated",
     "team.member_added",
     "team.member_removed",
     "team.member_role_updated",
     "team.builds_deploys_quota_exceeded",
-    // tenant (tenant.deleted is a shipped additive extension)
+    // tenant
     "tenant.past_due",
     "tenant.suspended",
     "tenant.reactivated",
     "tenant.deleted",
+    // principal (partner commerce lifecycle; §4/§5). `plan_reset` fires when a
+    // plan an external principal is assigned to drops out of the tenant's
+    // system-space plan catalog and the assignment falls back to the default.
+    "principal.plan_reset",
+    // Fires when an external principal creates a space that trips its plan's
+    // space-count quota under the `warn` enforcement policy — the create is
+    // allowed through and this records the overage instead of blocking.
+    "principal.space_quota_exceeded",
+    // Lifecycle transitions (§4). `suspended` darkens the principal's spaces
+    // (402 suspended page) and blocks its mutations; `unsuspended` restores both;
+    // `closed` is terminal. Each carries the acting actor so a Spacefast-applied
+    // status is distinguishable from a partner-applied one.
+    "principal.suspended",
+    "principal.unsuspended",
+    "principal.closed",
+    // partner usage ledger
+    "usage.threshold_crossed",
+    "usage.period_finalized",
+    "usage.corrected",
+    // principal notifications (partner API §7): the customer-facing notifications
+    // a partner white-labels. Spacefast delegates them — instead of emailing the
+    // partner's own end customer, it emits the event here for the partner to
+    // deliver. Defined in partner-notifications.ts (the subscribe-side catalog)
+    // and folded in so each is a first-class taxonomy code with a grammar row and
+    // a valid webhook filter.
+    ...PRINCIPAL_NOTIFICATION_EVENT_CODES,
     // comments
     "comment.token_minted",
     "comment.created",
     "comment.reply_created",
     "comment.archived",
     "comment.unarchived",
-    // abuse (additive extension: operator-tunable abuse-control telemetry)
+    // abuse
     "abuse_report.created",
     "abuse_report.updated",
-    // claim (additive extension: a claim attempt against a taken-down space is
-    // flagged, never silently 404ed — internal-docs/platform.md "Abuse Posture")
+    // claim (an attempt against a taken-down space is flagged, never silently 404ed)
     "claim.blocked_takedown",
     "claim.authority_rotated",
-    // user (additive extension: account lifecycle plus the 2FA and
-    // admin-impersonation effects that must surface through ActivityEvent —
-    // internal-docs/platform.md Better Auth usage). `user.created` fires once on
-    // signup; `user.signed_in` fires per non-impersonation session creation;
-    // `user.deleted` fires on account deletion and retains the analyticsId in
-    // its details so right-to-erasure can be completed in every provider.
+    // user. `user.signed_in` fires per non-impersonation session creation.
+    // `user.deleted` retains the analyticsId in its details so right-to-erasure
+    // can be completed in every provider.
     "user.created",
     "user.signed_in",
     "user.deleted",
@@ -131,20 +152,43 @@ export const ACTIVITY_EVENT_CODES = [
     "user.impersonation_stopped",
     "user.two_factor_enabled",
     "user.two_factor_disabled",
+    // Security notifications (auth/security-events.ts): every auth mutation that
+    // changes how the account can be entered lands here AND mails the owner
+    // through the same pipeline. Ids only in details, never addresses or names.
+    "user.password_set",
+    "user.password_changed",
+    "user.provider_linked",
+    "user.provider_unlinked",
+    "user.email_added",
+    "user.email_removed",
+    "user.primary_email_changed",
+    "user.superadmin_granted",
+    "user.superadmin_revoked",
+    "user.privacy_updated",
+    "user.deletion_requested",
+    "user.deletion_completed",
 ];
 const ACTIVITY_EVENT_CODE_SET = new Set(ACTIVITY_EVENT_CODES);
-const ACTIVITY_EVENT_RESOURCES = new Set(ACTIVITY_EVENT_CODES.map((code) => code.split(".", 1)[0]));
+// Every dot-delimited prefix a code carries, at each segment boundary — the set
+// a prefix wildcard may name. `version.ready` contributes `version`;
+// `principal.notification.claim` contributes both `principal` and
+// `principal.notification`, so a partner can subscribe to the whole
+// `principal.notification.*` class in one filter.
+const ACTIVITY_EVENT_PREFIXES = new Set(ACTIVITY_EVENT_CODES.flatMap((code) => {
+    const parts = code.split(".");
+    return parts.slice(0, -1).map((_, index) => parts.slice(0, index + 1).join("."));
+}));
 export function isActivityEventCode(value) {
     return ACTIVITY_EVENT_CODE_SET.has(value);
 }
-// Webhook `events` filters accept exact codes, prefix wildcards ("version.*"),
-// and the catch-all ["*"].
+// Webhook `events` filters accept exact codes, prefix wildcards ("version.*",
+// "principal.notification.*"), and the catch-all ["*"].
 export function isValidActivityEventFilter(filter) {
     if (filter === "*") {
         return true;
     }
     if (filter.endsWith(".*")) {
-        return ACTIVITY_EVENT_RESOURCES.has(filter.slice(0, -2));
+        return ACTIVITY_EVENT_PREFIXES.has(filter.slice(0, -2));
     }
     return ACTIVITY_EVENT_CODE_SET.has(filter);
 }
@@ -156,6 +200,7 @@ export function matchesActivityEventFilters(filters, code) {
 export const activityActorSchema = z.discriminatedUnion("type", [
     z.object({ type: z.literal("user"), id: z.string().min(1) }),
     z.object({ type: z.literal("api_key"), id: z.string().min(1) }),
+    z.object({ type: z.literal("partner_token"), id: z.string().min(1) }),
     z.object({ type: z.literal("oauth_client"), id: z.string().min(1) }),
     z.object({ type: z.literal("anonymous_claim"), id: z.string().min(1) }),
     z.object({ type: z.literal("system"), id: z.string().min(1) }),
@@ -169,6 +214,7 @@ export const activityEventSchema = z.object({
     id: z.string(),
     sequence: z.number().int().nonnegative(),
     tenantId: z.string(),
+    mode: tenantMode.describe("`test` when the event's tenant is a linked test tenant, `live` otherwise."),
     principal: activityPrincipalSchema.nullable(),
     spaceId: z.string().nullable(),
     actor: activityActorSchema,
@@ -181,9 +227,9 @@ export const activityQuerySchema = cursorListQuerySchema.extend({
     principalType: z
         .enum(["team", "external"])
         .optional()
-        .describe("Filter to events owned by a team or an external customer principal."),
-    principalId: z.string().min(1).optional().describe("Filter to a single principal id."),
-    spaceId: z.string().min(1).optional().describe("Filter to events for one space."),
+        .describe("Filter by owning principal type."),
+    principalId: z.string().min(1).optional().describe("Filter to one principal."),
+    spaceId: z.string().min(1).optional().describe("Filter to one space."),
     code: z
         .string()
         .min(1)