@greatwait/contracts 0.1.0-alpha.5 → 0.1.0-alpha.6

package/dist/members.js

@@ -0,0 +1,223 @@
+import { z } from "./zod.js";
+import { projectIdSchema } from "./identifiers.js";
+import { API_UNUSED_RESPONSE_SCHEMA, defineOperations, } from "./operation-definitions.js";
+import { requiredIdempotencyRequestHeaderSchema } from "./protocol.js";
+const requestOnly = globalThis
+    .GREATWAIT_API_REQUEST_REGISTRY;
+const withoutExamples = globalThis
+    .GREATWAIT_RUNTIME_WITHOUT_EXAMPLES;
+const contractsOnly = globalThis
+    .GREATWAIT_RUNTIME_CONTRACTS_ONLY;
+/** Assignable roles on the included Clerk plan. Billing is not offered. */
+export const managedMemberRoleSchema = z.enum(["admin", "member"]);
+export const memberIdSchema = z.string().regex(/^mem_[0-9a-f]{26}$/u);
+export const invitationIdSchema = z.string().regex(/^inv_[0-9a-f]{26}$/u);
+export const memberViewSchema = z.strictObject({
+    id: memberIdSchema,
+    email: z.string().email(),
+    name: z.string(),
+    role: managedMemberRoleSchema,
+    projects: z.array(projectIdSchema),
+    allProjects: z.boolean(),
+    self: z.boolean(),
+});
+export const memberListSchema = z.strictObject({
+    data: z.array(memberViewSchema),
+});
+export const invitationViewSchema = z.strictObject({
+    id: invitationIdSchema,
+    email: z.string().email(),
+    role: managedMemberRoleSchema,
+    projects: z.array(projectIdSchema),
+    status: z.enum(["pending", "accepted", "revoked", "expired"]),
+});
+export const invitationListSchema = z.strictObject({
+    data: z.array(invitationViewSchema),
+});
+export const memberInviteRequestSchema = z.strictObject({
+    email: z.string().email(),
+    role: managedMemberRoleSchema,
+    projects: z.array(projectIdSchema),
+});
+export const memberRoleRequestSchema = z.strictObject({
+    role: managedMemberRoleSchema,
+});
+export const memberRemovalRequestSchema = z.strictObject({
+    confirmed: z.literal(true),
+});
+export const memberActionSchema = z.strictObject({
+    completed: z.literal(true),
+    id: z.union([memberIdSchema, invitationIdSchema]),
+    project: projectIdSchema.optional(),
+});
+const member = {
+    id: "mem_0123456789abcdef0123456789",
+    email: "teammate@example.com",
+    name: "Teammate",
+    role: "member",
+    projects: ["proj_01h8xyz9k2m4n6p8r0t2v4w6y8"],
+    allProjects: false,
+    self: false,
+};
+const invitation = {
+    id: "inv_0123456789abcdef0123456789",
+    email: "teammate@example.com",
+    role: "member",
+    projects: member.projects,
+    status: "pending",
+};
+const common = {
+    creates: false,
+    idempotent: true,
+    principals: ["session", "oauth"],
+    scopes: ["members:manage"],
+    surfaces: ["api", "mock"],
+    problems: [
+        "invalid_request",
+        "not_found",
+        "state_conflict",
+        "service_unavailable",
+        "capability_not_configured",
+    ],
+    sessionAuthority: "organization",
+};
+const write = {
+    ...common,
+    mutates: true,
+    problems: [...common.problems, "idempotency_key_reused"],
+    requestHeaders: requiredIdempotencyRequestHeaderSchema,
+    response: requestOnly ? API_UNUSED_RESPONSE_SCHEMA : memberActionSchema,
+    example: withoutExamples ? {} : { completed: true, id: member.id },
+    mcp: { kind: "tool", destructive: false, openWorld: true },
+};
+export const MEMBER_OPERATIONS = defineOperations([
+    {
+        ...common,
+        id: "members.list",
+        method: "GET",
+        path: "/v1/organization/members",
+        mutates: false,
+        response: requestOnly ? API_UNUSED_RESPONSE_SCHEMA : memberListSchema,
+        example: withoutExamples ? {} : { data: [member] },
+        mcp: { kind: "tool", destructive: false, openWorld: false },
+        summary: requestOnly ? "" : "List organization members and project access",
+        description: contractsOnly
+            ? ""
+            : "An administrator lists current members. Members cannot enumerate or manage their colleagues. OAuth requires current administrator membership and explicit members:manage consent; API keys cannot manage people.",
+    },
+    {
+        ...common,
+        id: "invitations.list",
+        method: "GET",
+        path: "/v1/organization/invitations",
+        mutates: false,
+        response: requestOnly ? API_UNUSED_RESPONSE_SCHEMA : invitationListSchema,
+        example: withoutExamples ? {} : { data: [invitation] },
+        mcp: { kind: "tool", destructive: false, openWorld: false },
+        summary: requestOnly ? "" : "List organization invitations",
+        description: contractsOnly
+            ? ""
+            : "Lists invitations with current pending, accepted, revoked or expired status. No invitation ticket is returned.",
+    },
+    {
+        ...write,
+        id: "invitations.create",
+        creates: true,
+        method: "POST",
+        path: "/v1/organization/invitations",
+        request: memberInviteRequestSchema,
+        response: requestOnly ? API_UNUSED_RESPONSE_SCHEMA : invitationViewSchema,
+        example: withoutExamples ? {} : invitation,
+        requestExample: withoutExamples
+            ? {}
+            : {
+                email: invitation.email,
+                role: invitation.role,
+                projects: invitation.projects,
+            },
+        summary: requestOnly ? "" : "Invite a teammate to selected projects",
+        description: contractsOnly
+            ? ""
+            : "Sends a Clerk organization invitation as admin or member, with the selected project access. No seat pricing or product member limit applies. Admins have access to every project.",
+    },
+    {
+        ...write,
+        id: "invitations.resend",
+        example: withoutExamples ? {} : { completed: true, id: invitation.id },
+        method: "POST",
+        path: "/v1/organization/invitations/{invitationId}/resend",
+        request: z.strictObject({}),
+        requestExample: withoutExamples ? {} : {},
+        summary: requestOnly ? "" : "Resend a pending invitation",
+        description: contractsOnly
+            ? ""
+            : "Revokes the previous ticket before sending a replacement for the same role and selected projects. Accepted, revoked or expired invitations cannot be resent.",
+    },
+    {
+        ...write,
+        id: "invitations.revoke",
+        example: withoutExamples ? {} : { completed: true, id: invitation.id },
+        method: "POST",
+        path: "/v1/organization/invitations/{invitationId}/revoke",
+        request: memberRemovalRequestSchema,
+        requestExample: withoutExamples ? {} : { confirmed: true },
+        mcp: { kind: "tool", destructive: true, openWorld: true },
+        summary: requestOnly ? "" : "Revoke a pending invitation",
+        description: contractsOnly
+            ? ""
+            : "Requires explicit confirmation. The outstanding ticket no longer grants organization or project access.",
+    },
+    {
+        ...write,
+        id: "members.role",
+        method: "PATCH",
+        path: "/v1/organization/members/{memberId}",
+        request: memberRoleRequestSchema,
+        requestExample: withoutExamples ? {} : { role: "member" },
+        mcp: { kind: "tool", destructive: true, openWorld: true },
+        summary: requestOnly ? "" : "Change a member's role",
+        description: contractsOnly
+            ? ""
+            : "An administrator changes another person's role. Self role changes and demoting the last administrator are refused, including concurrent requests. Existing sessions and grants are narrowed on their next request.",
+    },
+    {
+        ...write,
+        id: "members.remove",
+        method: "POST",
+        path: "/v1/organization/members/{memberId}/remove",
+        request: memberRemovalRequestSchema,
+        requestExample: withoutExamples ? {} : { confirmed: true },
+        mcp: { kind: "tool", destructive: true, openWorld: true },
+        summary: requestOnly ? "" : "Remove an organization member",
+        description: contractsOnly
+            ? ""
+            : "Requires explicit confirmation. Removing the last administrator or oneself is refused. Subsequent sessions and grants lose access; organization-owned API keys remain valid and may be revoked separately.",
+    },
+    {
+        ...write,
+        id: "projectmembers.add",
+        method: "PUT",
+        path: "/v1/projects/{projectId}/members/{memberId}",
+        sessionAuthority: "headers",
+        request: z.strictObject({}),
+        requestExample: withoutExamples ? {} : {},
+        summary: requestOnly ? "" : "Add a member to a project",
+        description: contractsOnly
+            ? ""
+            : "A current administrator adds another organization member to an owned project. Foreign members and projects are indistinguishable from missing ones. No self addition.",
+    },
+    {
+        ...write,
+        id: "projectmembers.remove",
+        method: "POST",
+        path: "/v1/projects/{projectId}/members/{memberId}/remove",
+        sessionAuthority: "headers",
+        request: memberRemovalRequestSchema,
+        requestExample: withoutExamples ? {} : { confirmed: true },
+        mcp: { kind: "tool", destructive: true, openWorld: false },
+        summary: requestOnly ? "" : "Remove a member's project access",
+        description: contractsOnly
+            ? ""
+            : "Requires explicit confirmation. The member's existing sessions and OAuth grants lose access on the next request. Administrators retain access to every project; organization-owned API keys keep their single-project authority.",
+    },
+]);

package/dist/oauth.d.ts

@@ -414,6 +414,7 @@ export declare const consentPromptSchema: import("zod").ZodObject<{
         name: import("zod").ZodString;
     }, import("zod/v4/core").$strip>>;
     scopes: import("zod").ZodArray<import("zod").ZodEnum<{
+        "members:manage": "members:manage";
         "credentials:administer": "credentials:administer";
         "billing:write": "billing:write";
         "credentials:read": "credentials:read";
@@ -455,6 +456,7 @@ export declare const consentDecisionSchema: import("zod").ZodDiscriminatedUnion<
     }>;
     project: import("zod").ZodString;
     scopes: import("zod").ZodArray<import("zod").ZodEnum<{
+        "members:manage": "members:manage";
         "credentials:administer": "credentials:administer";
         "billing:write": "billing:write";
         "credentials:read": "credentials:read";
@@ -591,6 +593,7 @@ export declare const oauthGrantSchema: import("zod").ZodObject<{
     }>>;
     revokedAt: import("zod").ZodOptional<import("zod").ZodString>;
     scopes: import("zod").ZodArray<import("zod").ZodEnum<{
+        "members:manage": "members:manage";
         "credentials:administer": "credentials:administer";
         "billing:write": "billing:write";
         "credentials:read": "credentials:read";
@@ -637,6 +640,7 @@ export declare const oauthGrantListSchema: import("zod").ZodObject<{
         }>>;
         revokedAt: import("zod").ZodOptional<import("zod").ZodString>;
         scopes: import("zod").ZodArray<import("zod").ZodEnum<{
+            "members:manage": "members:manage";
             "credentials:administer": "credentials:administer";
             "billing:write": "billing:write";
             "credentials:read": "credentials:read";
@@ -691,6 +695,7 @@ export declare const oauthGrantRevokedSchema: import("zod").ZodObject<{
         }>>;
         revokedAt: import("zod").ZodOptional<import("zod").ZodString>;
         scopes: import("zod").ZodArray<import("zod").ZodEnum<{
+            "members:manage": "members:manage";
             "credentials:administer": "credentials:administer";
             "billing:write": "billing:write";
             "credentials:read": "credentials:read";
@@ -742,6 +747,7 @@ export declare const authorizationServerMetadataSchema: import("zod").ZodObject<
     }>>;
     revocation_endpoint: import("zod").ZodURL;
     scopes_supported: import("zod").ZodArray<import("zod").ZodEnum<{
+        "members:manage": "members:manage";
         "credentials:administer": "credentials:administer";
         "billing:write": "billing:write";
         "credentials:read": "credentials:read";
@@ -780,6 +786,7 @@ export declare const protectedResourceMetadataSchema: import("zod").ZodObject<{
     bearer_methods_supported: import("zod").ZodArray<import("zod").ZodLiteral<"header">>;
     resource: import("zod").ZodURL;
     scopes_supported: import("zod").ZodArray<import("zod").ZodEnum<{
+        "members:manage": "members:manage";
         "credentials:administer": "credentials:administer";
         "billing:write": "billing:write";
         "credentials:read": "credentials:read";

package/dist/operation-definitions.d.ts

@@ -1,9 +1,25 @@
 import type { OperationDefinition } from "./operations.js";
 /** Fail-closed response placeholder used by the hosted API's request-only registry. */
 export declare const API_UNUSED_RESPONSE_SCHEMA: import("zod").ZodNever;
-/** Keep registry ids precise without duplicating inferred Zod internals in every consumer declaration. */
+/**
+ * Keep registry ids precise without duplicating inferred Zod internals in every
+ * consumer declaration.
+ *
+ * The request schema is kept as well (W9-46): the generated client types each
+ * builder's body from it, and an entry declared here with only its id kept
+ * would leave that body `unknown` — the member and invitation commands took
+ * any object at all until this carried it.
+ */
 export declare function defineOperations<const T extends readonly OperationDefinition[]>(definitions: T): {
-    readonly [K in keyof T]: OperationDefinition & {
-        readonly id: T[K]["id"];
-    };
+    readonly [K in keyof T]: DefinedOperation<T[K]>;
 };
+type DefinedOperation<TEntry> = OperationDefinition & {
+    readonly id: TEntry extends {
+        readonly id: infer TId;
+    } ? TId : never;
+} & (TEntry extends {
+    readonly request: infer TRequest;
+} ? {
+    readonly request: TRequest;
+} : unknown);
+export {};

package/dist/operation-definitions.js

@@ -1,7 +1,15 @@
 import { never as neverSchema } from "zod";
 /** Fail-closed response placeholder used by the hosted API's request-only registry. */
 export const API_UNUSED_RESPONSE_SCHEMA = neverSchema();
-/** Keep registry ids precise without duplicating inferred Zod internals in every consumer declaration. */
+/**
+ * Keep registry ids precise without duplicating inferred Zod internals in every
+ * consumer declaration.
+ *
+ * The request schema is kept as well (W9-46): the generated client types each
+ * builder's body from it, and an entry declared here with only its id kept
+ * would leave that body `unknown` — the member and invitation commands took
+ * any object at all until this carried it.
+ */
 export function defineOperations(definitions) {
     return definitions;
 }