@whooshbang/contracts 2.0.0-rc.7 → 2.0.0

package/openapi/whooshbang-v1.yaml

@@ -1,10 +1,10 @@
 openapi: 3.1.1
 jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
 # whooshbang:public-origin production api https://api.whooshbang.com
-x-contract-version: 2.0.0-rc.7
+x-contract-version: 2.0.0
 info:
   title: WhooshBang API
-  version: 2.0.0-rc.7
+  version: 2.0.0
   description: |
     The V1 contract for human organization/project administration, project-scoped
     subscription links, and asynchronous text messages. A Clerk session selects
@@ -37,6 +37,8 @@ security:
 tags:
   - name: Organization
     description: The current Clerk organization projected as a WhooshBang organization.
+  - name: Teammates
+    description: The people in an organization, their roles and the projects each can see.
   - name: Projects
     description: Organization-scoped applications with transactionally bootstrapped test/live environments.
   - name: API credentials
@@ -266,8 +268,16 @@ paths:
   /v1/billing/subscription-changes:
     post:
       operationId: createSubscriptionChange
+      description: >-
+        Quote a new recurring selection without charging. Upgrades keep renewal
+        and charge the new plan or additional add-on units for the remaining
+        period, without unused-time credits or offsets. Paid dropped extras
+        remain available through their original expiry and do not renew.
+        Requires an administrator in the current organization. Without a current
+        plan or add-on the change starts one. Confirmation matches the saved exact
+        cash amount and charges the default card. Uncertain outcomes recover the
+        same owned change.
       summary: Quote an approved recurring change
-      description: Requires an administrator in the current organization. A quote does not charge. Without a current plan or add-on the change starts one. Confirmation matches the saved exact cash amount and charges the default card. Uncertain outcomes recover the same owned change.
       tags: [Organization]
       security:
         - clerkSession: []
@@ -310,7 +320,10 @@ paths:
     get:
       operationId: getSubscriptionChange
       summary: Recover an owned recurring change
-      description: Requires an administrator in the current organization. A quote does not charge. Without a current plan or add-on the change starts one. Confirmation matches the saved exact cash amount and charges the default card. Uncertain outcomes recover the same owned change.
+        Requires an administrator in the current organization. Without a current
+        plan or add-on the change starts one. Confirmation matches the saved exact
+        cash amount and charges the default card. Uncertain outcomes recover the
+        same owned change.
       tags: [Organization]
       security:
         - clerkSession: []
@@ -352,7 +365,10 @@ paths:
     post:
       operationId: confirmSubscriptionChange
       summary: Confirm the quoted card charge or scheduled reduction
-      description: Requires an administrator in the current organization. A quote does not charge. Without a current plan or add-on the change starts one. Confirmation matches the saved exact cash amount and charges the default card. Uncertain outcomes recover the same owned change.
+        Requires an administrator in the current organization. Without a current
+        plan or add-on the change starts one. Confirmation matches the saved exact
+        cash amount and charges the default card. Uncertain outcomes recover the
+        same owned change.
       tags: [Organization]
       security:
         - clerkSession: []
@@ -923,6 +939,207 @@ paths:
           $ref: "#/components/responses/Conflict"
         "429":
           $ref: "#/components/responses/RateLimited"
+  /v1/organization/teammates:
+    get:
+      operationId: listTeammates
+      summary: List the organization's teammates and open invitations
+      description: |
+        Returns every person in the organization with their role, the projects
+        they can see and whether they have joined, plus every invitation not yet
+        accepted. Any teammate may read it; only an admin may change it.
+      tags:
+        - Teammates
+      security:
+        - clerkSession: []
+        - bearerGrant: [teammates:read]
+      x-required-scopes: [teammates:read]
+      x-organization-membership: required
+      parameters:
+        - $ref: "#/components/parameters/ListAfterCursor"
+        - $ref: "#/components/parameters/ListPageLimit"
+        - $ref: "#/components/parameters/PageNumber"
+      responses:
+        "200":
+          description: The organization's teammates.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TeammateCollection"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+    post:
+      operationId: inviteTeammate
+      summary: Invite a teammate
+      description: |
+        Emails one invitation carrying the chosen role and, for a member or
+        messenger, the projects they will see. Nothing else is needed after they
+        accept. Inviting an address that is already invited or already a
+        teammate is refused rather than repeated.
+      tags:
+        - Teammates
+      security:
+        - clerkSession: []
+        - bearerGrant: [teammates:write]
+      x-required-scopes: [teammates:write]
+      x-organization-membership: required
+      x-required-membership-role: admin
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/InviteTeammateRequest"
+      responses:
+        "201":
+          description: The invitation.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Teammate"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/organization/teammates/{teammate_id}:
+    parameters:
+      - name: teammate_id
+        in: path
+        required: true
+        schema:
+          $ref: "../schemas/whooshbang-v1.schema.json#/$defs/OpaqueIdentifier"
+    delete:
+      operationId: removeTeammate
+      summary: Remove a teammate or revoke an invitation
+      description: |
+        Removes an active teammate from the organization, or revokes an
+        invitation. Removal applies to their next request, including requests
+        from MCP connections they authorized. The last admin cannot be removed.
+      tags:
+        - Teammates
+      security:
+        - clerkSession: []
+        - bearerGrant: [teammates:write]
+      x-required-scopes: [teammates:write]
+      x-organization-membership: required
+      x-required-membership-role: admin
+      responses:
+        "204":
+          description: The teammate was removed or the invitation revoked.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/organization/teammates/{teammate_id}/access:
+    parameters:
+      - name: teammate_id
+        in: path
+        required: true
+        schema:
+          $ref: "../schemas/whooshbang-v1.schema.json#/$defs/OpaqueIdentifier"
+    put:
+      operationId: setTeammateAccess
+      summary: Change a teammate's role and projects
+      description: |
+        Replaces the role and, for a member or messenger, the projects of an
+        active teammate or an open invitation. Narrowed access applies to their
+        next request. The last admin cannot be demoted.
+      tags:
+        - Teammates
+      security:
+        - clerkSession: []
+        - bearerGrant: [teammates:write]
+      x-required-scopes: [teammates:write]
+      x-organization-membership: required
+      x-required-membership-role: admin
+      x-repeat-semantics:
+        same_target: idempotent
+        secret_returned: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/TeammateAccessRequest"
+      responses:
+        "200":
+          description: The teammate with their new access.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Teammate"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/organization/teammates/{teammate_id}/resend:
+    parameters:
+      - name: teammate_id
+        in: path
+        required: true
+        schema:
+          $ref: "../schemas/whooshbang-v1.schema.json#/$defs/OpaqueIdentifier"
+    post:
+      operationId: resendTeammateInvitation
+      summary: Resend an invitation
+      description: |
+        Replaces an open invitation with a fresh one carrying the same role and
+        projects, and emails it again. The earlier link stops working.
+      tags:
+        - Teammates
+      security:
+        - clerkSession: []
+        - bearerGrant: [teammates:write]
+      x-required-scopes: [teammates:write]
+      x-organization-membership: required
+      x-required-membership-role: admin
+      responses:
+        "200":
+          description: The renewed invitation.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Teammate"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
   /v1/provider-installations:
     get:
       operationId: listProviderInstallations
@@ -8253,6 +8470,14 @@ components:
       $ref: "../schemas/whooshbang-v1.schema.json#/$defs/UpdateBillingReceiptEmailRequest"
     OrganizationProjection:
       $ref: ../schemas/whooshbang-v1.schema.json#/$defs/OrganizationProjection
+    Teammate:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/Teammate
+    TeammateCollection:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/TeammateCollection
+    TeammateAccessRequest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/TeammateAccessRequest
+    InviteTeammateRequest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/InviteTeammateRequest
     UpdateProjectRequest:
       $ref: ../schemas/whooshbang-v1.schema.json#/$defs/UpdateProjectRequest
     PrivacyMode:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whooshbang/contracts",
-  "version": "2.0.0-rc.7",
+  "version": "2.0.0",
   "description": "Versioned public contracts for WhooshBang",
   "private": false,
   "license": "MIT",
@@ -20,7 +20,7 @@
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "next"
+    "tag": "latest"
   },
   "files": [
     "CHANGELOG.md",
@@ -53,7 +53,6 @@
     "check": "npm run build && tsx scripts/check.ts",
     "generate": "tsx scripts/generate.ts",
     "lint": "eslint src scripts test --max-warnings=0",
-    "pack:verified": "npm run check && tsx scripts/pack.ts",
     "test": "vitest run --no-file-parallelism",
     "type-check": "tsc --noEmit -p tsconfig.json"
   },

package/schemas/core-scenario.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/core-scenario.schema.json",
-  "x-contract-version": "2.0.0-rc.7",
+  "x-contract-version": "2.0.0",
   "title": "CoreContractScenario",
   "description": "A deterministic C0-02 semantic, state, idempotency, or isolation scenario.",
   "type": "object",

package/schemas/events/agent-binding-degraded-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/agent-binding-degraded-v1.schema.json",
-  "x-contract-version": "2.0.0-rc.7",
+  "x-contract-version": "2.0.0",
   "title": "AgentBindingDegradedEventV1",
   "description": "An agent binding entered a provider-neutral degraded state.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/AgentBindingDegradedEvent"

package/schemas/events/interaction-expired-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/interaction-expired-v1.schema.json",
-  "x-contract-version": "2.0.0-rc.7",
+  "x-contract-version": "2.0.0",
   "title": "InteractionExpiredEventV1",
   "description": "An interaction reached its terminal expiry without a valid answer.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/InteractionExpiredEvent"

package/schemas/events/interaction-received-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/interaction-received-v1.schema.json",
-  "x-contract-version": "2.0.0-rc.7",
+  "x-contract-version": "2.0.0",
   "title": "InteractionReceivedEventV1",
   "description": "One authenticated, provider-neutral interaction answer was received.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/InteractionReceivedEvent"

package/schemas/events/message-delivered-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/message-delivered-v1.schema.json",
-  "x-contract-version": "2.0.0-rc.7",
+  "x-contract-version": "2.0.0",
   "title": "MessageDeliveredEventV1",
   "description": "A provider supplied trustworthy evidence that a message was delivered.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/MessageDeliveredEvent"

package/schemas/events/message-expired-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/message-expired-v1.schema.json",
-  "x-contract-version": "2.0.0-rc.7",
+  "x-contract-version": "2.0.0",
   "title": "MessageExpiredEventV1",
   "description": "A message expired before reaching a later delivery state.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/MessageExpiredEvent"

package/schemas/events/message-failed-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/message-failed-v1.schema.json",
-  "x-contract-version": "2.0.0-rc.7",
+  "x-contract-version": "2.0.0",
   "title": "MessageFailedEventV1",
   "description": "A message reached a classified terminal failure.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/MessageFailedEvent"

package/schemas/events/message-provider-accepted-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/message-provider-accepted-v1.schema.json",
-  "x-contract-version": "2.0.0-rc.7",
+  "x-contract-version": "2.0.0",
   "title": "MessageProviderAcceptedEventV1",
   "description": "The provider accepted a message without implying delivery.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/MessageProviderAcceptedEvent"

package/schemas/events/subscription-activated-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/subscription-activated-v1.schema.json",
-  "x-contract-version": "2.0.0-rc.7",
+  "x-contract-version": "2.0.0",
   "title": "SubscriptionActivatedEventV1",
   "description": "A subscription became active with a safe public channel binding.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/SubscriptionActivatedEvent"

package/schemas/events/subscription-revoked-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/subscription-revoked-v1.schema.json",
-  "x-contract-version": "2.0.0-rc.7",
+  "x-contract-version": "2.0.0",
   "title": "SubscriptionRevokedEventV1",
   "description": "A subscription and its safe public channel binding were revoked.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/SubscriptionRevokedEvent"

package/schemas/events/whooshbang-event-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/whooshbang-event-v1.schema.json",
-  "x-contract-version": "2.0.0-rc.7",
+  "x-contract-version": "2.0.0",
   "title": "WhooshBangEventV1ContractDocument",
   "description": "Strict public customer-event envelope and initial WhooshBang event union.",
   "oneOf": [
@@ -694,40 +694,80 @@
       ]
     },
     "SubscriptionAssertedData": {
-      "type": "object",
-      "required": [
-        "consent_assertion_id",
-        "binding_id",
-        "subscriber_id",
-        "notifier_id",
-        "channel",
-        "state",
-        "activated_at"
-      ],
-      "properties": {
-        "binding_id": {
-          "$ref": "#/$defs/OpaqueIdentifier"
-        },
-        "subscriber_id": {
-          "$ref": "#/$defs/OpaqueIdentifier"
-        },
-        "notifier_id": {
-          "$ref": "#/$defs/OpaqueIdentifier"
-        },
-        "channel": {
-          "const": "email"
-        },
-        "state": {
-          "const": "activated"
-        },
-        "activated_at": {
-          "$ref": "#/$defs/Timestamp"
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "consent_assertion_id",
+            "binding_id",
+            "subscriber_id",
+            "notifier_id",
+            "channel",
+            "state",
+            "activated_at"
+          ],
+          "properties": {
+            "binding_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "subscriber_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "notifier_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "channel": {
+              "const": "email"
+            },
+            "state": {
+              "const": "activated"
+            },
+            "activated_at": {
+              "$ref": "#/$defs/Timestamp"
+            },
+            "consent_assertion_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            }
+          },
+          "additionalProperties": false
         },
-        "consent_assertion_id": {
-          "$ref": "#/$defs/OpaqueIdentifier"
+        {
+          "type": "object",
+          "required": [
+            "service_assertion_id",
+            "binding_id",
+            "subscriber_id",
+            "notifier_id",
+            "channel",
+            "state",
+            "activated_at"
+          ],
+          "properties": {
+            "binding_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "subscriber_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "notifier_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "channel": {
+              "const": "email"
+            },
+            "state": {
+              "const": "activated"
+            },
+            "activated_at": {
+              "$ref": "#/$defs/Timestamp"
+            },
+            "service_assertion_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            }
+          },
+          "additionalProperties": false
         }
-      },
-      "additionalProperties": false
+      ]
     },
     "SubscriptionAssertedEvent": {
       "allOf": [
@@ -748,40 +788,80 @@
       ]
     },
     "SubscriptionAssertedRevokedData": {
-      "type": "object",
-      "required": [
-        "consent_assertion_id",
-        "binding_id",
-        "subscriber_id",
-        "notifier_id",
-        "channel",
-        "state",
-        "revoked_at"
-      ],
-      "properties": {
-        "binding_id": {
-          "$ref": "#/$defs/OpaqueIdentifier"
-        },
-        "subscriber_id": {
-          "$ref": "#/$defs/OpaqueIdentifier"
-        },
-        "notifier_id": {
-          "$ref": "#/$defs/OpaqueIdentifier"
-        },
-        "channel": {
-          "const": "email"
-        },
-        "state": {
-          "const": "revoked"
-        },
-        "revoked_at": {
-          "$ref": "#/$defs/Timestamp"
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "consent_assertion_id",
+            "binding_id",
+            "subscriber_id",
+            "notifier_id",
+            "channel",
+            "state",
+            "revoked_at"
+          ],
+          "properties": {
+            "binding_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "subscriber_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "notifier_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "channel": {
+              "const": "email"
+            },
+            "state": {
+              "const": "revoked"
+            },
+            "revoked_at": {
+              "$ref": "#/$defs/Timestamp"
+            },
+            "consent_assertion_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            }
+          },
+          "additionalProperties": false
         },
-        "consent_assertion_id": {
-          "$ref": "#/$defs/OpaqueIdentifier"
+        {
+          "type": "object",
+          "required": [
+            "service_assertion_id",
+            "binding_id",
+            "subscriber_id",
+            "notifier_id",
+            "channel",
+            "state",
+            "revoked_at"
+          ],
+          "properties": {
+            "binding_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "subscriber_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "notifier_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "channel": {
+              "const": "email"
+            },
+            "state": {
+              "const": "revoked"
+            },
+            "revoked_at": {
+              "$ref": "#/$defs/Timestamp"
+            },
+            "service_assertion_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            }
+          },
+          "additionalProperties": false
         }
-      },
-      "additionalProperties": false
+      ]
     },
     "SubscriptionAssertedRevokedEvent": {
       "allOf": [

package/schemas/fixture-index.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/fixture-index.schema.json",
-  "x-contract-version": "2.0.0-rc.7",
+  "x-contract-version": "2.0.0",
   "title": "CoreFixtureIndex",
   "description": "The machine-readable index of deterministic C0-02 through C0-04 golden fixtures.",
   "type": "object",