@k9o/core 1.2.0 → 1.3.0

package/src/org.ts

@@ -7,36 +7,55 @@
  * across accessible orgs) — `client.org` is the singular bound-org
  * namespace with member / group / smtp / audit / gate sub-namespaces.
  *
- * Org-plane URL grammar: requests route against the
- * `<orgSlug>.api.k9o.io/` org subdomain WITHOUT the `@<projectSlug>/`
- * prefix used by project-plane requests. The gateway resolves the org
- * context from the subdomain.
+ * Org-plane URL grammar: requests go to the org's API host (`<orgSlug>.api.<apex>`) WITHOUT the
+ * `@<projectSlug>/` prefix used by project-plane requests. The gateway resolves the org context from the host.
  */
 
 import { request, type HttpClientConfig } from "./http.ts";
 import { orgPath } from "./url-grammar.ts";
 import type { Envelope } from "./envelope.ts";
 import type { LLMModelId } from "./compute/llms.ts";
+import type { Org } from "./orgs.ts";
 
 // ----------------------------------------------------------------------
 // Types
 // ----------------------------------------------------------------------
 
 export type OrgMember = {
-  /** `u_<base62>`. */
+  /** `usr_<base62>`. */
   userId: string;
+  orgId: string;
   email: string;
-  /** Org-level role enum. */
+  displayName: string;
+  /** Org-level role. */
   role: "ORG_OWNER" | "ORG_ADMIN" | "ORG_BILLING_ADMIN" | "ORG_MEMBER";
-  joinedAt: string;
-  status: "active" | "invited" | "suspended";
+  invitedAt: string;
+  /** `null` until the invitation is accepted. */
+  acceptedAt: string | null;
+  status: "active" | "suspended";
+  /** `invited` until accepted, then the same as `status`. */
+  state: "invited" | "active" | "suspended";
+  suspendedAt: string | null;
+};
+
+/**
+ * Answer of `members.invite` when the email has no account yet (HTTP 202): an invitation was created
+ * instead of a member. `delivery` says whether the invitation email went out.
+ */
+export type OrgInviteResult = {
+  invitation: { id: string; orgId: string; email: string; role: OrgMember["role"]; expiresAt: string };
+  delivery: "sent" | "not_configured" | "failed";
 };
 
 export type OrgGroup = {
   /** `grp_<base62>`. */
   id: string;
+  orgId: string;
   name: string;
-  memberCount: number;
+  description: string | null;
+  /** Groups come from an identity provider. */
+  source: "idp";
+  sourceGroupId: string;
   createdAt: string;
 };
 
@@ -44,7 +63,7 @@ export type OrgRoleGrant = {
   /** `grt_<base62>`. */
   id: string;
   userId: string;
-  role: "ORG_ADMIN" | "ORG_BILLING_ADMIN";
+  role: "ORG_OWNER" | "ORG_ADMIN" | "ORG_BILLING_ADMIN" | "ORG_AUDITOR" | "ORG_MEMBER";
   grantedBy: string;
   grantedAt: string;
   revokedAt: string | null;
@@ -53,74 +72,90 @@ export type OrgRoleGrant = {
 };
 
 /**
- * Org-level audit event 6-event family.
- *
- * Event types (closed set at v2.1.132):
- *   - `data.write.org.member_invited`
- *   - `data.write.org.member_removed`
- *   - `data.write.org.role_granted`
- *   - `data.write.org.role_revoked`
- *   - `data.write.org.idp_config_changed`
- *   - `data.write.org.settings_updated`
- *
- * `targetKind` is `org` for all; `targetId` is the orgId.
+ * Org-level audit event: member invited or removed, role granted or revoked, identity provider
+ * or settings changed.
  */
 export type OrgAuditEvent = {
   id: string;
   type: string;
   actorId: string | null;
-  targetKind: "org";
-  targetId: string;
+  targetKind: string | null;
+  targetId: string | null;
   payload: Record<string, unknown>;
-  occurredAt: string;
+  createdAt: string;
   requestId: string | null;
   traceId: string | null;
 };
 
 /**
- * Org SMTP configuration. Sensitive fields (passwordRef)
- * are sequestered in Kibo enclave; the SDK stores only the reference.
+ * Org SMTP configuration, as the gateway takes it in the `smtpConfig` field of PATCH /org.
+ * The password is never sent: `passwordRef` is a reference to a stored secret.
  */
 export type SmtpConfig = {
   host: string;
   port: number;
   username: string;
-  /** Kibo enclave credential reference; opaque token. */
+  /** Reference to the stored SMTP password; opaque token. */
   passwordRef: string;
-  fromEmail: string;
-  fromName: string;
-  encryption: "none" | "starttls" | "tls";
-  replyToEmail?: string | undefined;
+  fromAddress: string;
+  fromName?: string | undefined;
 };
 
 export type SmtpTestEmailInput = {
   to: string;
-  /** Optional override of the from address for the test send (defaults to fromEmail). */
-  fromOverride?: string | undefined;
+  subject?: string | undefined;
 };
 
 export type SmtpTestEmailResult = {
-  ok: boolean;
-  /** Diagnostic message returned by the SMTP server (success or error detail). */
-  diagnostic: string;
-  /** ISO 8601 timestamp of the test attempt. */
-  attemptedAt: string;
+  accepted: boolean;
+  /** Which SMTP configuration serves the org: `org` when it has its own, else `platform`. */
+  resolvedTier: "org" | "platform";
+  to: string;
+  /** `true` while the gateway does not send the message itself. */
+  dryRun: boolean;
+};
+
+export type OrgDefaultLlm = {
+  orgId: string;
+  defaultModelId: string;
+  updatedAt: string;
+  updatedBy: string | null;
 };
 
+export type OrgIdpProviderKind =
+  | "google" | "github" | "microsoft" | "oidc" | "saml" | "scim" | "ldap" | "active_directory" | "apple" | "facebook" | "twitter";
+
 export type OrgIdpProvider = {
-  /** `idp_<base62>`. */
   id: string;
-  name: string;
-  /** Protocol/vendor (e.g. "okta-saml", "azure-ad-oidc", "google-workspace"). */
-  kind: string;
+  idpProvider: OrgIdpProviderKind;
+  displayName: string;
+  clientId: string;
   enabled: boolean;
   createdAt: string;
 };
 
+/** Body of POST /identity-providers. `clientSecretRef` is a reference to a stored secret, never the secret itself. */
 export type CreateOrgIdpInput = {
-  name: string;
-  kind: string;
-  config: Record<string, unknown>;
+  idpProvider: OrgIdpProviderKind;
+  displayName: string;
+  clientId: string;
+  clientSecretRef: string;
+  tierGating: "free_tier_ok" | "ridge_plus";
+  redirectUri?: string | undefined;
+  metadataUrl?: string | null | undefined;
+  attributeMap?: Record<string, unknown> | undefined;
+  enabled?: boolean | undefined;
+};
+
+/** Body of PATCH /identity-providers/<id>. */
+export type UpdateOrgIdpInput = {
+  displayName?: string | undefined;
+  clientId?: string | undefined;
+  clientSecretRef?: string | undefined;
+  redirectUri?: string | undefined;
+  metadataUrl?: string | null | undefined;
+  attributeMap?: Record<string, unknown> | undefined;
+  enabled?: boolean | undefined;
 };
 
 // ----------------------------------------------------------------------
@@ -129,23 +164,24 @@ export type CreateOrgIdpInput = {
 
 function makeMembersNamespace(config: HttpClientConfig) {
   return {
-    /** GET /members (org-plane LIST). */
-    async list(opts?: { limit?: number | undefined; cursor?: string | undefined; status?: OrgMember["status"] | undefined }): Promise<Envelope<ReadonlyArray<OrgMember>>> {
+    /** GET /members (org-plane LIST). The route is not paged; it filters by userId, role, acceptanceStatus, status and state. */
+    async list(opts?: {
+      userId?: string | undefined; role?: OrgMember["role"] | undefined;
+      acceptanceStatus?: "accepted" | "pending" | undefined; status?: "active" | "suspended" | undefined; state?: string | undefined;
+    }): Promise<Envelope<ReadonlyArray<OrgMember>>> {
       return request(config, { method: "GET", path: orgPath("members"), query: opts });
     },
 
-    /** POST /members — invite a new org member by email. */
-    async invite(input: { email: string; role: OrgMember["role"] }): Promise<Envelope<OrgMember>> {
+    /**
+     * POST /members — add a member by email. An existing user becomes a member at once (201, the member row);
+     * an unknown email gets an invitation (202, `{ invitation, delivery }`).
+     */
+    async invite(input: { email: string; role: OrgMember["role"] }): Promise<Envelope<OrgMember | OrgInviteResult>> {
       return request(config, { method: "POST", path: orgPath("members"), body: input });
     },
 
-    /** GET /members/<userId> — single-read (existing endpoint). */
-    async get(userId: string): Promise<Envelope<OrgMember>> {
-      return request(config, { method: "GET", path: orgPath(`members/${encodeURIComponent(userId)}`) });
-    },
-
-    /** DELETE /members/<userId> — remove a member from the org. */
-    async remove(userId: string): Promise<Envelope<{ removed: boolean }>> {
+    /** DELETE /members/<userId> — remove a member from the org. The gateway answers 204 with no body. */
+    async remove(userId: string): Promise<Envelope<undefined>> {
       return request(config, { method: "DELETE", path: orgPath(`members/${encodeURIComponent(userId)}`) });
     },
   };
@@ -154,104 +190,78 @@ function makeMembersNamespace(config: HttpClientConfig) {
 function makeGroupsNamespace(config: HttpClientConfig) {
   return {
     /** GET /groups (org-plane LIST). */
-    async list(opts?: { limit?: number; cursor?: string }): Promise<Envelope<ReadonlyArray<OrgGroup>>> {
+    async list(opts?: { userId?: string | undefined }): Promise<Envelope<ReadonlyArray<OrgGroup>>> {
       return request(config, { method: "GET", path: orgPath("groups"), query: opts });
     },
 
-    /** POST /groups — create a new group. */
-    async create(input: { name: string }): Promise<Envelope<OrgGroup>> {
-      return request(config, { method: "POST", path: orgPath("groups"), body: input });
-    },
-
-    /** GET /groups/<groupId> — single-read (pre-cement existing endpoint). */
+    /** GET /groups/<groupId> — single-read. */
     async get(groupId: string): Promise<Envelope<OrgGroup>> {
       return request(config, { method: "GET", path: orgPath(`groups/${encodeURIComponent(groupId)}`) });
     },
 
-    /** DELETE /groups/<groupId> — remove a group. */
-    async delete(groupId: string): Promise<Envelope<{ deleted: boolean }>> {
-      return request(config, { method: "DELETE", path: orgPath(`groups/${encodeURIComponent(groupId)}`) });
-    },
   };
 }
 
 function makeOrgAuditLogNamespace(config: HttpClientConfig) {
   return {
     /**
-     * GET /audit-log (org-plane).
-     * Distinct from project-plane `client.audit.query()` which routes to
-     * `@<projectSlug>/audit-log`. Org-plane events cover the 6-event family
-     * (member_invited/removed/role_granted/revoked/
-     * idp_config_changed/settings_updated).
+     * GET /audit-log (org-plane), newest first. The route reads `type` and `limit` (1 to 500, default 100) only.
+     * Distinct from project-plane `client.audit.query()` which routes to `@<projectSlug>/audit-log`.
      */
-    async query(opts?: {
-      since?: string | undefined; until?: string | undefined; type?: string | undefined; actorId?: string | undefined;
-      targetKind?: string | undefined; targetId?: string | undefined; limit?: number | undefined; cursor?: string | undefined;
-    }): Promise<Envelope<ReadonlyArray<OrgAuditEvent>>> {
+    async query(opts?: { type?: string | undefined; limit?: number | undefined }): Promise<Envelope<ReadonlyArray<OrgAuditEvent>>> {
       return request(config, { method: "GET", path: orgPath("audit-log"), query: opts });
     },
-
-    /** Convenience: recent events (defaults to 5 minute window). */
-    async tail(opts?: { sinceMinutes?: number; limit?: number }): Promise<Envelope<ReadonlyArray<OrgAuditEvent>>> {
-      const minutes = opts?.sinceMinutes ?? 5;
-      const since = new Date(Date.now() - minutes * 60_000).toISOString();
-      return request(config, {
-        method: "GET",
-        path: orgPath("audit-log"),
-        query: { since, limit: opts?.limit ?? 100 },
-      });
-    },
   };
 }
 
 function makeOrgGateNamespace(config: HttpClientConfig) {
   return {
     roles: {
-      /** GET /org-role-grants — list active grants ask 4. */
-      async list(opts?: { userId?: string | undefined; role?: OrgRoleGrant["role"] | undefined; includeRevoked?: boolean | undefined }): Promise<Envelope<ReadonlyArray<OrgRoleGrant>>> {
-        return request(config, { method: "GET", path: orgPath("org-role-grants"), query: opts });
+      /** GET /role-grants — list role grants. */
+      async list(): Promise<Envelope<ReadonlyArray<OrgRoleGrant>>> {
+        return request(config, { method: "GET", path: orgPath("role-grants") });
       },
 
-      /** POST /org-role-grants — grant an ORG_ADMIN or ORG_BILLING_ADMIN role. */
-      async grant(input: { userId: string; role: OrgRoleGrant["role"] }): Promise<Envelope<OrgRoleGrant>> {
-        return request(config, { method: "POST", path: orgPath("org-role-grants"), body: input });
+      /** POST /role-grants — grant an org role. */
+      async grant(input: { userId: string; role: OrgRoleGrant["role"]; decisionReason?: string | undefined }): Promise<Envelope<OrgRoleGrant>> {
+        return request(config, { method: "POST", path: orgPath("role-grants"), body: input });
       },
 
-      /** GET /org-role-grants/<grantId> — single-read. */
+      /** GET /role-grants/<grantId> — single-read. */
       async get(grantId: string): Promise<Envelope<OrgRoleGrant>> {
-        return request(config, { method: "GET", path: orgPath(`org-role-grants/${encodeURIComponent(grantId)}`) });
+        return request(config, { method: "GET", path: orgPath(`role-grants/${encodeURIComponent(grantId)}`) });
       },
 
-      /** DELETE /org-role-grants/<grantId> — revoke a grant (soft delete; sets revokedAt). */
-      async revoke(grantId: string): Promise<Envelope<OrgRoleGrant>> {
-        return request(config, { method: "DELETE", path: orgPath(`org-role-grants/${encodeURIComponent(grantId)}`) });
+      /** DELETE /role-grants/<grantId> — revoke a grant (soft delete; sets revokedAt). */
+      async revoke(grantId: string, opts?: { decisionReason?: string | undefined }): Promise<Envelope<OrgRoleGrant>> {
+        return request(config, { method: "DELETE", path: orgPath(`role-grants/${encodeURIComponent(grantId)}`), ...(opts ? { body: opts } : {}) });
       },
     },
 
     idpProviders: {
-      /** GET /idp-providers — list configured org operator IdP providers ask 7. */
+      /** GET /identity-providers — list configured identity providers. */
       async list(): Promise<Envelope<ReadonlyArray<OrgIdpProvider>>> {
-        return request(config, { method: "GET", path: orgPath("idp-providers") });
+        return request(config, { method: "GET", path: orgPath("identity-providers") });
       },
 
-      /** POST /idp-providers — create a new IdP integration. */
+      /** POST /identity-providers — create a new IdP integration. */
       async create(input: CreateOrgIdpInput): Promise<Envelope<OrgIdpProvider>> {
-        return request(config, { method: "POST", path: orgPath("idp-providers"), body: input });
+        return request(config, { method: "POST", path: orgPath("identity-providers"), body: input });
       },
 
-      /** GET /idp-providers/<idpId>. */
+      /** GET /identity-providers/<idpId>. */
       async get(idpId: string): Promise<Envelope<OrgIdpProvider>> {
-        return request(config, { method: "GET", path: orgPath(`idp-providers/${encodeURIComponent(idpId)}`) });
+        return request(config, { method: "GET", path: orgPath(`identity-providers/${encodeURIComponent(idpId)}`) });
       },
 
-      /** PATCH /idp-providers/<idpId> — update config or enable/disable. */
-      async configure(idpId: string, patch: { name?: string; enabled?: boolean; config?: Record<string, unknown> }): Promise<Envelope<OrgIdpProvider>> {
-        return request(config, { method: "PATCH", path: orgPath(`idp-providers/${encodeURIComponent(idpId)}`), body: patch });
+      /** PATCH /identity-providers/<idpId> — update settings or enable/disable. */
+      async configure(idpId: string, patch: UpdateOrgIdpInput): Promise<Envelope<OrgIdpProvider>> {
+        return request(config, { method: "PATCH", path: orgPath(`identity-providers/${encodeURIComponent(idpId)}`), body: patch });
       },
 
-      /** DELETE /idp-providers/<idpId>. */
+      /** DELETE /identity-providers/<idpId>. */
       async delete(idpId: string): Promise<Envelope<{ deleted: boolean }>> {
-        return request(config, { method: "DELETE", path: orgPath(`idp-providers/${encodeURIComponent(idpId)}`) });
+        return request(config, { method: "DELETE", path: orgPath(`identity-providers/${encodeURIComponent(idpId)}`) });
       },
     },
   };
@@ -260,21 +270,10 @@ function makeOrgGateNamespace(config: HttpClientConfig) {
 function makeSmtpNamespace(config: HttpClientConfig) {
   return {
     /**
-     * GET /org/smtp — read current SMTP config.
-     * Returns null when no org-level SMTP is configured (falls back to
-     * platform SMTP 3-tier cascade).
-     */
-    async get(): Promise<Envelope<SmtpConfig | null>> {
-      return request(config, { method: "GET", path: orgPath("org/smtp") });
-    },
-
-    /**
-     * PATCH /orgs/<orgSlug> with `smtpConfig` body — set or update SMTP.
-     * PATCH on the org resource accepts smtpConfig.
-     * Passwords route through Kibo enclave — SDK accepts plaintext at
-     * the SDK boundary; gateway stores the reference.
+     * PATCH /org with `smtpConfig` body — set or update SMTP. Answers the org record.
+     * The body carries `passwordRef` (a reference to the stored password), not the password.
      */
-    async set(config_: Omit<SmtpConfig, "passwordRef"> & { password: string }): Promise<Envelope<SmtpConfig>> {
+    async set(config_: SmtpConfig): Promise<Envelope<Org>> {
       return request(config, { method: "PATCH", path: orgPath("org"), body: { smtpConfig: config_ } });
     },
 
@@ -287,8 +286,8 @@ function makeSmtpNamespace(config: HttpClientConfig) {
       return request(config, { method: "POST", path: orgPath("org/smtp/test-email"), body: input });
     },
 
-    /** PATCH /orgs/<orgSlug> with `smtpConfig: null` — clear org-level SMTP. */
-    async unset(): Promise<Envelope<{ cleared: boolean }>> {
+    /** PATCH /org with `smtpConfig: null` — clear org-level SMTP. Answers the org record. */
+    async unset(): Promise<Envelope<Org>> {
       return request(config, { method: "PATCH", path: orgPath("org"), body: { smtpConfig: null } });
     },
   };
@@ -297,21 +296,20 @@ function makeSmtpNamespace(config: HttpClientConfig) {
 function makeDefaultLlmNamespace(config: HttpClientConfig) {
   return {
     /**
-     * GET /org/default-llm — read the org-default LLM model id
-     *. Returns `null` when no explicit default is set (gateway
-     * falls back to `mistral-7b`). ORG_ADMIN read; tier-gated.
+     * GET /default-llm — read the org-default LLM model id.
+     * Any accepted member of the org may read it.
      */
-    async get(): Promise<Envelope<LLMModelId | null>> {
-      return request(config, { method: "GET", path: orgPath("org/default-llm") });
+    async get(): Promise<Envelope<OrgDefaultLlm>> {
+      return request(config, { method: "GET", path: orgPath("default-llm") });
     },
 
     /**
-     * PATCH /org/default-llm — set the org-default LLM.
-     * ORG_ADMIN only. The model must be available to the org's tier per
+     * PATCH /default-llm — set the org-default LLM.
+     * ORG_ADMIN or ORG_OWNER only. The model must be available to the org's tier
      * or the gateway returns K9O_TIER_FEATURE_GATED.
      */
-    async set(input: { modelId: LLMModelId }): Promise<Envelope<LLMModelId>> {
-      return request(config, { method: "PATCH", path: orgPath("org/default-llm"), body: input });
+    async set(input: { modelId: LLMModelId }): Promise<Envelope<{ orgId: string; defaultModelId: string }>> {
+      return request(config, { method: "PATCH", path: orgPath("default-llm"), body: input });
     },
   };
 }
@@ -322,25 +320,25 @@ function makeDefaultLlmNamespace(config: HttpClientConfig) {
 
 export function makeOrgNamespace(config: HttpClientConfig) {
   return {
-    /** Member lifecycle — list / invite / get / remove. */
+    /** Member lifecycle — list / invite / remove. */
     members: makeMembersNamespace(config),
-    /** Group lifecycle — list / create / get / delete. */
+    /** Groups — list / get (read-only). */
     groups: makeGroupsNamespace(config),
-    /** Org-plane audit log — query / tail. Distinct from project-plane `client.audit`. */
+    /** Org-plane audit log — query. Distinct from project-plane `client.audit`. */
     auditLog: makeOrgAuditLogNamespace(config),
     /** Gate (IAK) org-level surfaces — role-grants + IdP-providers. */
     gate: makeOrgGateNamespace(config),
-    /** Org-level SMTP config — get / set / test / unset. */
+    /** Org-level SMTP config — set / test / unset. */
     smtp: makeSmtpNamespace(config),
     /** Org-default LLM — get / set (ORG_ADMIN). */
     defaultLLM: makeDefaultLlmNamespace(config),
 
     /**
-     * GET /org — read the current org (slug + name + status + settings).
+     * GET /org — read the current org (slug, displayName, products, billing tier, your role).
      * Mirrors `client.orgs.current()` for symmetry; `client.org.get()` is
      * the singular-namespace convention for use within an org-bound client.
      */
-    async get(): Promise<Envelope<{ id: string; slug: string; name: string; status: string; createdAt: string }>> {
+    async get(): Promise<Envelope<Org>> {
       return request(config, { method: "GET", path: orgPath("org") });
     },
   };

package/src/orgs.ts

@@ -26,14 +26,27 @@ import { request, type HttpClientConfig } from "./http.ts";
 import { orgPath, validateSlug } from "./url-grammar.ts";
 import type { Envelope } from "./envelope.ts";
 
+/**
+ * Org record, as the gateway returns it. `list` rows add `viaToken` and `consoleDomain`;
+ * `get`, `current` and `restore` add `customDomain` and `deletedAt`.
+ */
 export type Org = {
   /** `org_<base62>`. */
   id: string;
   slug: string;
-  name: string;
-  status: "active" | "suspended" | "soft-deleted";
+  displayName: string;
+  products: ReadonlyArray<string>;
+  billingTier: string;
+  signupProduct: string;
+  /** The caller's role in the org. */
+  role: string;
   createdAt: string;
-  updatedAt: string | null;
+  customDomain?: string | null | undefined;
+  deletedAt?: string | null | undefined;
+  /** List rows only: `true` when the org is reached through the token rather than a membership. */
+  viaToken?: boolean | undefined;
+  /** List rows only: the org's Console host. */
+  consoleDomain?: string | undefined;
 };
 
 export function makeOrgsNamespace(config: HttpClientConfig) {

package/src/policies.ts

@@ -13,9 +13,9 @@
  *   - `delete(bundleId)`                  → DELETE /@<slug>/policies/<id>
  *   - `publish(bundleId)`                 → POST   /@<slug>/policies/<id>/publish
  *
- * Per: only Pathmaker-class roles author policy; only
- * Custodian-class roles publish. `validate` is read-only and any role
- * with policy-read can lint a candidate bundle.
+ * Only authoring roles write policy and only custodian roles publish.
+ * `validate` is read-only and any role with policy-read can lint a
+ * candidate document.
  */
 
 import { request, type HttpClientConfig } from "./http.ts";
@@ -25,29 +25,63 @@ import type { Envelope } from "./envelope.ts";
 export type PolicyBundle = {
   /** `pol_<base62>`. */
   id: string;
-  name: string;
-  version: number;
-  status: "draft" | "published" | "deactivated";
-  rules: Record<string, unknown>;
+  projectId: string;
+  status: "draft" | "published" | "superseded";
+  /** The policy document. */
+  policy: PolicyDocument;
+  /** The rules catalogue, when the bundle carries one. */
+  rules?: unknown;
+  createdBy: string;
   createdAt: string;
   publishedAt: string | null;
-  createdBy: string;
+  supersededAt: string | null;
+  supersededBy: string | null;
+  source: "rest" | "migration" | "cli";
+  editorMode: "visual" | "json" | "unspecified";
+  supersededReason: string | null;
+  /** Id of a queued publish awaiting a second approver, else `null`. */
+  pendingChangeId: string | null;
+};
+
+/** Answer of `publish`: the publish is queued for approval (HTTP 202). */
+export type PolicyPublishResult = {
+  pendingChangeId: string;
+  bundleId: string;
+  status: "pending_approval";
 };
 
+/**
+ * The policy document: sections keyed by resource kind (`collections`,
+ * `storage`, `tools`, `functions`, `secrets`, `streams`, `analytics`);
+ * other keys are allowed.
+ */
+export type PolicyDocument = Record<string, unknown>;
+
 export type CreatePolicyInput = {
-  name: string;
-  rules: Record<string, unknown>;
+  policy: PolicyDocument;
+  rules?: unknown;
+  editorMode?: "visual" | "json" | "unspecified" | undefined;
 };
 
 export type UpdatePolicyInput = {
-  name?: string;
-  rules?: Record<string, unknown>;
+  policy: PolicyDocument;
+  rules?: unknown;
+  editorMode?: "visual" | "json" | "unspecified" | undefined;
+};
+
+export type ValidatePolicyInput = {
+  policy: PolicyDocument;
+  rules?: unknown;
 };
 
+/** Validation failures are errors, so a successful validate always answers `{ valid: true }`. */
 export type ValidatePolicyResult = {
-  valid: boolean;
-  errors: ReadonlyArray<{ rule: string; message: string }>;
-  warnings: ReadonlyArray<{ rule: string; message: string }>;
+  valid: true;
+};
+
+/** Optional publish controls; property names are the gateway's. */
+export type PublishPolicyOptions = {
+  acknowledgeSelfLockout?: boolean | undefined;
 };
 
 function requireProjectSlug(config: HttpClientConfig): string {
@@ -68,8 +102,8 @@ export function makePoliciesNamespace(config: HttpClientConfig) {
       });
     },
 
-    /** List all policy bundles (draft + published + deactivated). */
-    async list(opts?: { status?: PolicyBundle["status"] | undefined; limit?: number | undefined; cursor?: string | undefined }): Promise<Envelope<ReadonlyArray<PolicyBundle>>> {
+    /** List all policy bundles (draft + published + superseded). */
+    async list(opts?: { status?: PolicyBundle["status"] | undefined }): Promise<Envelope<ReadonlyArray<PolicyBundle>>> {
       const slug = requireProjectSlug(config);
       return request(config, {
         method: "GET",
@@ -88,8 +122,8 @@ export function makePoliciesNamespace(config: HttpClientConfig) {
       });
     },
 
-    /** Lint a candidate rule set without persisting. */
-    async validate(input: { rules: Record<string, unknown> }): Promise<Envelope<ValidatePolicyResult>> {
+    /** Lint a candidate policy document without persisting. */
+    async validate(input: ValidatePolicyInput): Promise<Envelope<ValidatePolicyResult>> {
       const slug = requireProjectSlug(config);
       return request(config, {
         method: "POST",
@@ -107,7 +141,7 @@ export function makePoliciesNamespace(config: HttpClientConfig) {
       });
     },
 
-    /** Patch a draft bundle. Cannot patch published bundles (publish→republish flow). */
+    /** Replace a draft bundle's policy document. Cannot patch published bundles (publish→republish flow). */
     async update(bundleId: string, patch: UpdatePolicyInput): Promise<Envelope<PolicyBundle>> {
       const slug = requireProjectSlug(config);
       return request(config, {
@@ -117,8 +151,8 @@ export function makePoliciesNamespace(config: HttpClientConfig) {
       });
     },
 
-    /** Delete a draft bundle. Cannot delete published bundles. */
-    async delete(bundleId: string): Promise<Envelope<{ deleted: boolean }>> {
+    /** Delete a draft bundle. Cannot delete published bundles. The gateway answers 204 with no body. */
+    async delete(bundleId: string): Promise<Envelope<undefined>> {
       const slug = requireProjectSlug(config);
       return request(config, {
         method: "DELETE",
@@ -126,12 +160,17 @@ export function makePoliciesNamespace(config: HttpClientConfig) {
       });
     },
 
-    /** Publish a draft bundle — transitions to `published` + becomes active for the project. */
-    async publish(bundleId: string): Promise<Envelope<PolicyBundle>> {
+    /**
+     * Publish a draft bundle. The gateway answers 202 with `{ pendingChangeId, bundleId }`: the publish waits for
+     * approval, then the bundle becomes active. Pass `acknowledgeSelfLockout: true` to proceed when the bundle
+     * would remove your own read access to a collection.
+     */
+    async publish(bundleId: string, options?: PublishPolicyOptions): Promise<Envelope<PolicyPublishResult>> {
       const slug = requireProjectSlug(config);
       return request(config, {
         method: "POST",
         path: projectPath(slug, `policies/${encodeURIComponent(bundleId)}/publish`),
+        ...(options !== undefined ? { body: options } : {}),
       });
     },
   };