@greatwait/contracts 0.1.0-alpha.2 → 0.1.0-alpha.4

package/README.md

@@ -32,20 +32,22 @@ are not JavaScript.
 
 ## What ships
 
-| Path                                    | What it is                                                                                  |
-| --------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `generated/v1/openapi.json`             | The public API, as OpenAPI                                                                  |
-| `generated/v1/openapi.mock.json`        | The contract mock's surface, labelled separately so it can never be read as the product API |
-| `generated/v1/schemas/`                 | JSON Schema per operation, request and response                                             |
-| `generated/v1/snippets/`                | curl, JavaScript and MCP examples per operation                                             |
-| `generated/v1/first-value-journey.json` | The canonical first-value sequence, as data                                                 |
-| `generated/v1/policy-matrix.json`       | Who may call what, derived from the registry                                                |
-| `generated/v1/manifest.json`            | The index of everything above, with the contract version                                    |
+| Path                                    | What it is                                               |
+| --------------------------------------- | -------------------------------------------------------- |
+| `generated/v1/openapi.json`             | The public API, as OpenAPI                               |
+| `generated/v1/schemas/`                 | JSON Schema per operation, request and response          |
+| `generated/v1/snippets/`                | curl, JavaScript and MCP examples per operation          |
+| `generated/v1/first-value-journey.json` | The canonical first-value sequence, as data              |
+| `generated/v1/policy-matrix.json`       | Who may call what, derived from the registry             |
+| `generated/v1/manifest.json`            | The index of everything above, with the contract version |
 
 All of it is generated from one registry, so a change to an operation changes
 every artifact at once. Nothing here is hand-maintained beside the code it
 describes.
 
+The repository also generates `openapi.mock.json` for contract-mock validation.
+That internal QA surface is deliberately excluded from the published package.
+
 ## The conventions the schemas encode
 
 - **Identifiers** are opaque, prefixed and server-assigned. Compare them for

package/dist/authority.d.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 import type { ProblemCode } from "./problems.js";
 /**
  * Who is asking, and what they may do.
@@ -26,20 +26,20 @@ import type { ProblemCode } from "./problems.js";
  * third if one is ever added.
  */
 export declare const ENVIRONMENT_KINDS_IN_ORDER: readonly ["test", "live"];
-export declare const environmentKindSchema: z.ZodEnum<{
+export declare const environmentKindSchema: import("zod").ZodEnum<{
     test: "test";
     live: "live";
 }>;
 export type EnvironmentKind = z.infer<typeof environmentKindSchema>;
-export declare const authoritySchema: z.ZodObject<{
-    environment: z.ZodString;
-    environmentKind: z.ZodEnum<{
+export declare const authoritySchema: import("zod").ZodObject<{
+    environment: import("zod").ZodString;
+    environmentKind: import("zod").ZodEnum<{
         test: "test";
         live: "live";
     }>;
-    organization: z.ZodString;
-    project: z.ZodString;
-}, z.core.$strip>;
+    organization: import("zod").ZodString;
+    project: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
 export type Authority = z.infer<typeof authoritySchema>;
 /**
  * The initial scope vocabulary. Scopes are `resource:action`, lower case, and
@@ -50,9 +50,10 @@ export type Authority = z.infer<typeof authoritySchema>;
  * client is permitted, and what the granting member's current role allows.
  * Nothing here can exceed a human's own access.
  */
-export declare const SCOPES: readonly ["credentials:administer", "credentials:read", "credentials:write", "endpoints:read", "endpoints:write", "forecast:read", "grants:read", "grants:write", "occurrences:read", "occurrences:redeliver", "projects:read", "projects:write", "schedules:read", "schedules:write", "usage:read"];
-export declare const scopeSchema: z.ZodEnum<{
+export declare const SCOPES: readonly ["credentials:administer", "billing:write", "credentials:read", "credentials:write", "endpoints:read", "endpoints:write", "forecast:read", "grants:read", "grants:write", "occurrences:read", "occurrences:redeliver", "projects:administer", "projects:read", "projects:write", "schedules:read", "schedules:write", "usage:read"];
+export declare const scopeSchema: import("zod").ZodEnum<{
     "credentials:administer": "credentials:administer";
+    "billing:write": "billing:write";
     "credentials:read": "credentials:read";
     "credentials:write": "credentials:write";
     "endpoints:read": "endpoints:read";
@@ -62,6 +63,7 @@ export declare const scopeSchema: z.ZodEnum<{
     "grants:write": "grants:write";
     "occurrences:read": "occurrences:read";
     "occurrences:redeliver": "occurrences:redeliver";
+    "projects:administer": "projects:administer";
     "projects:read": "projects:read";
     "projects:write": "projects:write";
     "schedules:read": "schedules:read";
@@ -95,24 +97,25 @@ export declare function effectiveScopes(granted: readonly Scope[]): Set<Scope>;
  *   gives for one that does not exist.
  */
 export declare const PRINCIPAL_KINDS: readonly ["api-credential", "oauth", "session"];
-export declare const principalKindSchema: z.ZodEnum<{
+export declare const principalKindSchema: import("zod").ZodEnum<{
     "api-credential": "api-credential";
     oauth: "oauth";
     session: "session";
 }>;
 export type PrincipalKind = z.infer<typeof principalKindSchema>;
-export declare const principalSchema: z.ZodObject<{
-    authority: z.ZodObject<{
-        environment: z.ZodString;
-        environmentKind: z.ZodEnum<{
+export declare const principalSchema: import("zod").ZodObject<{
+    authority: import("zod").ZodObject<{
+        environment: import("zod").ZodString;
+        environmentKind: import("zod").ZodEnum<{
             test: "test";
             live: "live";
         }>;
-        organization: z.ZodString;
-        project: z.ZodString;
-    }, z.core.$strip>;
-    scopes: z.ZodArray<z.ZodEnum<{
+        organization: import("zod").ZodString;
+        project: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>;
+    scopes: import("zod").ZodArray<import("zod").ZodEnum<{
         "credentials:administer": "credentials:administer";
+        "billing:write": "billing:write";
         "credentials:read": "credentials:read";
         "credentials:write": "credentials:write";
         "endpoints:read": "endpoints:read";
@@ -122,18 +125,19 @@ export declare const principalSchema: z.ZodObject<{
         "grants:write": "grants:write";
         "occurrences:read": "occurrences:read";
         "occurrences:redeliver": "occurrences:redeliver";
+        "projects:administer": "projects:administer";
         "projects:read": "projects:read";
         "projects:write": "projects:write";
         "schedules:read": "schedules:read";
         "schedules:write": "schedules:write";
         "usage:read": "usage:read";
     }>>;
-    via: z.ZodEnum<{
+    via: import("zod").ZodEnum<{
         "api-credential": "api-credential";
         oauth: "oauth";
         session: "session";
     }>;
-}, z.core.$strip>;
+}, import("zod/v4/core").$strip>;
 export type Principal = z.infer<typeof principalSchema>;
 export interface AccessRequest {
     readonly principal: Principal;
@@ -215,3 +219,62 @@ export declare const SESSION_AUTHORITY_HEADERS: {
     readonly environment: "Greatwait-Environment";
     readonly project: "Greatwait-Project";
 };
+/**
+ * The authority a presented credential carries, answered back to its holder.
+ *
+ * **Why this exists at all.** The authority tuple is fixed at issue for a key
+ * and at consent for a grant — and until W10-01 nothing published it. A holder
+ * could act, and could not ask what it was acting *on*. The gap is invisible
+ * to a browser, which resolves its own project from a session it can see, and
+ * invisible to a documentation page, which tells a reader to substitute values
+ * they already know. It is not invisible to a command-line client: after
+ * `login` it holds a working token and cannot tell the person in front of it
+ * which project it is in, or whether the schedule they are about to create is
+ * a `test` one or a `live` one. Both were observable only by listing something
+ * the project already owned, which a new project does not have.
+ *
+ * **No organization, following every other `/v1` response.** Tenancy above the
+ * project is not a name this surface publishes, and a caller that cannot name
+ * an organization anywhere has no use for one here.
+ *
+ * **`scopes` is what was granted, not what was asked for and not what it
+ * implies.** A grant is capped by the consenting member's role and a key by
+ * what the issuer chose, so this is narrower than any request; it is also the
+ * *raw* list rather than `effectiveScopes`, which expands a write into its
+ * read. Publishing the expansion would make this answer disagree with the
+ * credential's own row in `credentials.list` and with what the consent screen
+ * showed the member — three places, two answers — and a caller that needs to
+ * know whether a scope is implied can apply the same published expansion the
+ * service does.
+ */
+export declare const credentialContextSchema: import("zod").ZodObject<{
+    environmentKind: import("zod").ZodEnum<{
+        test: "test";
+        live: "live";
+    }>;
+    principal: import("zod").ZodEnum<{
+        "api-credential": "api-credential";
+        oauth: "oauth";
+    }>;
+    project: import("zod").ZodString;
+    scopes: import("zod").ZodArray<import("zod").ZodEnum<{
+        "credentials:administer": "credentials:administer";
+        "billing:write": "billing:write";
+        "credentials:read": "credentials:read";
+        "credentials:write": "credentials:write";
+        "endpoints:read": "endpoints:read";
+        "endpoints:write": "endpoints:write";
+        "forecast:read": "forecast:read";
+        "grants:read": "grants:read";
+        "grants:write": "grants:write";
+        "occurrences:read": "occurrences:read";
+        "occurrences:redeliver": "occurrences:redeliver";
+        "projects:administer": "projects:administer";
+        "projects:read": "projects:read";
+        "projects:write": "projects:write";
+        "schedules:read": "schedules:read";
+        "schedules:write": "schedules:write";
+        "usage:read": "usage:read";
+    }>>;
+}, import("zod/v4/core").$strip>;
+export type CredentialContext = z.infer<typeof credentialContextSchema>;

package/dist/authority.js

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 import { environmentIdSchema, organizationIdSchema, projectIdSchema, } from "./identifiers.js";
 /**
  * Who is asking, and what they may do.
@@ -60,6 +60,8 @@ export const SCOPES = [
      * the row rather than of the route.
      */
     "credentials:administer",
+    /** Change desired billing policy and advance an approved policy revision. */
+    "billing:write",
     "credentials:read",
     "credentials:write",
     "endpoints:read",
@@ -83,6 +85,14 @@ export const SCOPES = [
     "grants:write",
     "occurrences:read",
     "occurrences:redeliver",
+    /**
+     * Stop, restore, or permanently destroy a whole project.
+     *
+     * Kept separate from `projects:write`: renaming is ordinary reversible work,
+     * while these operations affect every member and every schedule in the
+     * project. Organization administrators hold this scope; members do not.
+     */
+    "projects:administer",
     "projects:read",
     /**
      * Create a project, with its `test` and `live` environments.
@@ -104,7 +114,7 @@ export const SCOPES = [
     "schedules:read",
     "schedules:write",
     /**
-     * See what this project was charged for.
+     * See terminal occurrence volume and the organization's exact attempt ledger.
      *
      * A scope of its own rather than a corner of `schedules:read`, because the
      * two answer to different people: a service account that lists schedules to
@@ -259,3 +269,38 @@ export const SESSION_AUTHORITY_HEADERS = {
     environment: "Greatwait-Environment",
     project: "Greatwait-Project",
 };
+/**
+ * The authority a presented credential carries, answered back to its holder.
+ *
+ * **Why this exists at all.** The authority tuple is fixed at issue for a key
+ * and at consent for a grant — and until W10-01 nothing published it. A holder
+ * could act, and could not ask what it was acting *on*. The gap is invisible
+ * to a browser, which resolves its own project from a session it can see, and
+ * invisible to a documentation page, which tells a reader to substitute values
+ * they already know. It is not invisible to a command-line client: after
+ * `login` it holds a working token and cannot tell the person in front of it
+ * which project it is in, or whether the schedule they are about to create is
+ * a `test` one or a `live` one. Both were observable only by listing something
+ * the project already owned, which a new project does not have.
+ *
+ * **No organization, following every other `/v1` response.** Tenancy above the
+ * project is not a name this surface publishes, and a caller that cannot name
+ * an organization anywhere has no use for one here.
+ *
+ * **`scopes` is what was granted, not what was asked for and not what it
+ * implies.** A grant is capped by the consenting member's role and a key by
+ * what the issuer chose, so this is narrower than any request; it is also the
+ * *raw* list rather than `effectiveScopes`, which expands a write into its
+ * read. Publishing the expansion would make this answer disagree with the
+ * credential's own row in `credentials.list` and with what the consent screen
+ * showed the member — three places, two answers — and a caller that needs to
+ * know whether a scope is implied can apply the same published expansion the
+ * service does.
+ */
+export const credentialContextSchema = z.object({
+    environmentKind: environmentKindSchema,
+    /** How this credential authenticated. Never `session`: see the operation. */
+    principal: z.enum(["api-credential", "oauth"]),
+    project: projectIdSchema,
+    scopes: z.array(scopeSchema).min(1),
+});