@greatwait/contracts 0.1.0-alpha.1

package/dist/tenancy.d.ts

@@ -0,0 +1,178 @@
+import { z } from "zod";
+/**
+ * Organizations, projects, and environments.
+ *
+ * The tenancy spine. An organization owns projects; a project owns exactly two
+ * environments, `test` and `live`. Every scheduling resource belongs to one
+ * `(organization, project, environment)` tuple, and that tuple comes from a
+ * verified principal rather than from anything a client sends — see
+ * `authority.ts`.
+ *
+ * **Environments are not organizations.** The W1-02 guide forbids modelling them
+ * as duplicated organizations, and the reason is worth stating: a customer would
+ * then have two tenants to keep in step, membership would have to be granted
+ * twice, and "the same code serves test and live" — the property that makes a
+ * test environment worth having — would stop being true.
+ */
+/**
+ * An organization, in Greatwait's own identifier space.
+ *
+ * `externalId` is the Clerk organization this projects from. The two are kept
+ * apart deliberately: a Greatwait `org_…` is what appears in public responses, so
+ * our surface never depends on the identity vendor and a caller never learns a
+ * second spelling of their own tenant. See `identity.ts`.
+ */
+export declare const organizationSchema: z.ZodObject<{
+    externalId: z.ZodString;
+    id: z.ZodString;
+    version: z.ZodNumber;
+}, z.core.$strip>;
+export type Organization = z.infer<typeof organizationSchema>;
+/**
+ * Whether a project accepts new work.
+ *
+ * `archived` is reversible and stops new schedules without destroying history;
+ * `deleted` is a tombstone. Deletion keeps the row rather than removing it,
+ * because a project identifier that vanishes makes every occurrence and audit
+ * entry that referenced it unexplainable — and because reusing a deleted
+ * project's identifier must be impossible.
+ */
+export declare const PROJECT_STATUSES: readonly ["active", "archived", "deleted"];
+export declare const projectStatusSchema: z.ZodEnum<{
+    active: "active";
+    archived: "archived";
+    deleted: "deleted";
+}>;
+export type ProjectStatus = z.infer<typeof projectStatusSchema>;
+/**
+ * A human label for a project. Mutable, non-unique, and never an identifier.
+ *
+ * Deliberately not a slug. A name that doubles as an identifier invites callers
+ * to construct URLs from it, and then renaming a project becomes a breaking
+ * change for them. Identifiers are server-assigned and opaque; names are for
+ * people.
+ */
+export declare const projectNameSchema: z.ZodString;
+export declare const projectSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    organization: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        archived: "archived";
+        deleted: "deleted";
+    }>;
+    version: z.ZodNumber;
+}, z.core.$strip>;
+export type Project = z.infer<typeof projectSchema>;
+/**
+ * One of a project's two environments.
+ *
+ * `kind` is immutable, and that is the whole point of the type. A mutable kind
+ * would mean a test environment could become live — silently promoting every
+ * schedule, endpoint and credential inside it, all of which were created under
+ * the assumption that nothing they did could reach a customer.
+ */
+export declare const environmentSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        test: "test";
+        live: "live";
+    }>;
+    project: z.ZodString;
+}, z.core.$strip>;
+export type Environment = z.infer<typeof environmentSchema>;
+/**
+ * A project together with both of its environments.
+ *
+ * Returned as a unit because a project without both is not a valid state: they
+ * are provisioned in the same transaction, and any caller that has one has both.
+ */
+export declare const provisionedProjectSchema: z.ZodObject<{
+    environments: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            test: "test";
+            live: "live";
+        }>;
+        project: z.ZodString;
+    }, z.core.$strip>>;
+    project: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        organization: z.ZodString;
+        status: z.ZodEnum<{
+            active: "active";
+            archived: "archived";
+            deleted: "deleted";
+        }>;
+        version: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ProvisionedProject = z.infer<typeof provisionedProjectSchema>;
+/**
+ * What a signed-in member is told about a project they may act in.
+ *
+ * **Not `provisionedProjectSchema`, deliberately.** That shape carries
+ * `organization`, `status`, `version` and both environment *identifiers*, and
+ * publishing environment ids would make them public names — while nothing on
+ * `/v1` takes one: every operation that names an environment names its
+ * `kind`. Publishing an identifier no operation accepts invites a client to
+ * build on it and then constrains us to keep it.
+ *
+ * `{id, name}` is exactly what the OAuth consent prompt already hands a browser,
+ * and the framing there applies here word for word: this is a display aid rather
+ * than an authorization control. Whatever the list shows, the authority for a
+ * request is re-resolved from the member's organization when the request
+ * arrives.
+ */
+export declare const projectSummarySchema: z.ZodObject<{
+    environmentKinds: z.ZodArray<z.ZodEnum<{
+        test: "test";
+        live: "live";
+    }>>;
+    id: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+export type ProjectSummary = z.infer<typeof projectSummarySchema>;
+/**
+ * Every project in the member's organization that they may act in.
+ *
+ * **Unpaged, with a stated ceiling, because the store beneath it is.**
+ * `listProjects` reads an organization's projects in one go; declaring a page
+ * request over it would publish a `limit` nothing honours, which is the drift
+ * the artifact pipeline exists to prevent. The cap is what makes the absence of
+ * paging a bounded promise rather than an unbounded one — an organization that
+ * reaches it is a signal to page this properly, not a customer who quietly gets
+ * a truncated answer.
+ */
+export declare const PROJECT_LIST_LIMIT = 200;
+export declare const projectListSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        environmentKinds: z.ZodArray<z.ZodEnum<{
+            test: "test";
+            live: "live";
+        }>>;
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ProjectList = z.infer<typeof projectListSchema>;
+/**
+ * What a member sends to create a project.
+ *
+ * **A name and nothing else.** The organization comes from the verified session
+ * and is never read from input — the rule `authority.ts` states for every
+ * request — and the two environments are provisioned with the project rather
+ * than asked for, because `provisionProject` mints both in one transaction and
+ * a project observable without one of them is a state this product does not
+ * have.
+ *
+ * There is no `status`: a project is created `active`, and a caller that could
+ * create an archived one would be creating something it must then unarchive
+ * through an operation that does not exist.
+ */
+export declare const projectCreateRequestSchema: z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strip>;
+export type ProjectCreateRequest = z.infer<typeof projectCreateRequestSchema>;

package/dist/tenancy.js

@@ -0,0 +1,145 @@
+import { z } from "zod";
+import { environmentKindSchema } from "./authority.js";
+import { environmentIdSchema, organizationIdSchema, projectIdSchema, } from "./identifiers.js";
+import { versionSchema } from "./protocol.js";
+/**
+ * Organizations, projects, and environments.
+ *
+ * The tenancy spine. An organization owns projects; a project owns exactly two
+ * environments, `test` and `live`. Every scheduling resource belongs to one
+ * `(organization, project, environment)` tuple, and that tuple comes from a
+ * verified principal rather than from anything a client sends — see
+ * `authority.ts`.
+ *
+ * **Environments are not organizations.** The W1-02 guide forbids modelling them
+ * as duplicated organizations, and the reason is worth stating: a customer would
+ * then have two tenants to keep in step, membership would have to be granted
+ * twice, and "the same code serves test and live" — the property that makes a
+ * test environment worth having — would stop being true.
+ */
+/**
+ * An organization, in Greatwait's own identifier space.
+ *
+ * `externalId` is the Clerk organization this projects from. The two are kept
+ * apart deliberately: a Greatwait `org_…` is what appears in public responses, so
+ * our surface never depends on the identity vendor and a caller never learns a
+ * second spelling of their own tenant. See `identity.ts`.
+ */
+export const organizationSchema = z.object({
+    externalId: z.string().min(1),
+    id: organizationIdSchema,
+    version: versionSchema,
+});
+/**
+ * Whether a project accepts new work.
+ *
+ * `archived` is reversible and stops new schedules without destroying history;
+ * `deleted` is a tombstone. Deletion keeps the row rather than removing it,
+ * because a project identifier that vanishes makes every occurrence and audit
+ * entry that referenced it unexplainable — and because reusing a deleted
+ * project's identifier must be impossible.
+ */
+export const PROJECT_STATUSES = ["active", "archived", "deleted"];
+export const projectStatusSchema = z.enum(PROJECT_STATUSES);
+/**
+ * A human label for a project. Mutable, non-unique, and never an identifier.
+ *
+ * Deliberately not a slug. A name that doubles as an identifier invites callers
+ * to construct URLs from it, and then renaming a project becomes a breaking
+ * change for them. Identifiers are server-assigned and opaque; names are for
+ * people.
+ */
+export const projectNameSchema = z
+    .string()
+    .trim()
+    .min(1, "must not be blank")
+    .max(120, "must be at most 120 characters");
+export const projectSchema = z.object({
+    id: projectIdSchema,
+    name: projectNameSchema,
+    organization: organizationIdSchema,
+    status: projectStatusSchema,
+    version: versionSchema,
+});
+/**
+ * One of a project's two environments.
+ *
+ * `kind` is immutable, and that is the whole point of the type. A mutable kind
+ * would mean a test environment could become live — silently promoting every
+ * schedule, endpoint and credential inside it, all of which were created under
+ * the assumption that nothing they did could reach a customer.
+ */
+export const environmentSchema = z.object({
+    id: environmentIdSchema,
+    kind: environmentKindSchema,
+    project: projectIdSchema,
+});
+/**
+ * A project together with both of its environments.
+ *
+ * Returned as a unit because a project without both is not a valid state: they
+ * are provisioned in the same transaction, and any caller that has one has both.
+ */
+export const provisionedProjectSchema = z.object({
+    environments: z
+        .array(environmentSchema)
+        .length(2, "a project has exactly two environments"),
+    project: projectSchema,
+});
+/**
+ * What a signed-in member is told about a project they may act in.
+ *
+ * **Not `provisionedProjectSchema`, deliberately.** That shape carries
+ * `organization`, `status`, `version` and both environment *identifiers*, and
+ * publishing environment ids would make them public names — while nothing on
+ * `/v1` takes one: every operation that names an environment names its
+ * `kind`. Publishing an identifier no operation accepts invites a client to
+ * build on it and then constrains us to keep it.
+ *
+ * `{id, name}` is exactly what the OAuth consent prompt already hands a browser,
+ * and the framing there applies here word for word: this is a display aid rather
+ * than an authorization control. Whatever the list shows, the authority for a
+ * request is re-resolved from the member's organization when the request
+ * arrives.
+ */
+export const projectSummarySchema = z.object({
+    environmentKinds: z
+        .array(environmentKindSchema)
+        .length(2, "a project has exactly two environments"),
+    id: projectIdSchema,
+    name: projectNameSchema,
+});
+/**
+ * Every project in the member's organization that they may act in.
+ *
+ * **Unpaged, with a stated ceiling, because the store beneath it is.**
+ * `listProjects` reads an organization's projects in one go; declaring a page
+ * request over it would publish a `limit` nothing honours, which is the drift
+ * the artifact pipeline exists to prevent. The cap is what makes the absence of
+ * paging a bounded promise rather than an unbounded one — an organization that
+ * reaches it is a signal to page this properly, not a customer who quietly gets
+ * a truncated answer.
+ */
+export const PROJECT_LIST_LIMIT = 200;
+export const projectListSchema = z.object({
+    data: z
+        .array(projectSummarySchema)
+        .max(PROJECT_LIST_LIMIT, "more projects than this response can carry; paging is required"),
+});
+/**
+ * What a member sends to create a project.
+ *
+ * **A name and nothing else.** The organization comes from the verified session
+ * and is never read from input — the rule `authority.ts` states for every
+ * request — and the two environments are provisioned with the project rather
+ * than asked for, because `provisionProject` mints both in one transaction and
+ * a project observable without one of them is a state this product does not
+ * have.
+ *
+ * There is no `status`: a project is created `active`, and a caller that could
+ * create an archived one would be creating something it must then unarchive
+ * through an operation that does not exist.
+ */
+export const projectCreateRequestSchema = z.object({
+    name: projectNameSchema,
+});