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

package/dist/tenancy.d.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 /**
  * Organizations, projects, and environments.
  *
@@ -22,48 +22,70 @@ import { z } from "zod";
  * 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 declare const organizationSchema: import("zod").ZodObject<{
+    externalId: import("zod").ZodString;
+    id: import("zod").ZodString;
+    version: import("zod").ZodNumber;
+}, import("zod/v4/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.
+ * `archived` is reversible and stops new work without destroying history.
+ * `deleted` is terminal and exists only while permanent destruction is being
+ * completed; a successful delete removes the project and all of its rows.
  */
 export declare const PROJECT_STATUSES: readonly ["active", "archived", "deleted"];
-export declare const projectStatusSchema: z.ZodEnum<{
+export declare const projectStatusSchema: import("zod").ZodEnum<{
     active: "active";
-    archived: "archived";
     deleted: "deleted";
+    archived: "archived";
 }>;
 export type ProjectStatus = z.infer<typeof projectStatusSchema>;
 /**
- * A human label for a project. Mutable, non-unique, and never an identifier.
+ * A human label for a project. Mutable, unique within its organization by
+ * `projectNameKey`, 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.
+ * people — which is also why two projects may not share one (FXO-2256): a
+ * switcher with two "Billing reminders" in it is a switcher nobody can use.
+ */
+export declare const projectNameSchema: import("zod").ZodString;
+/**
+ * How two project names are compared for uniqueness (FXO-2256).
+ *
+ * Per organization, ignoring case and surrounding or repeated spaces:
+ * "Billing reminders" and "billing  Reminders" are one name, which is the
+ * mistake somebody actually makes — retyping a name they already used.
+ *
+ * **Two statements of one rule, kept equal by construction.** The database
+ * computes this key itself, in SQL, on every insert and rename (the triggers
+ * in `apps/api/migrations/0014_project_name_uniqueness.sql`), and a unique
+ * index over it refuses a second active project with the same one — so no
+ * writer can bypass the rule by forgetting a column. This function is the
+ * form's and the store's copy, for a refusal before the request, and it is
+ * deliberately no cleverer than SQLite: case folds for ASCII letters only
+ * (`lower()` there knows no other alphabet), and the whitespace it collapses
+ * is spaces, tabs and newlines. Two names differing only in the case of an
+ * accented letter are two names — an edge stated rather than hidden, because
+ * a rule the form applied and the database did not would refuse in the form
+ * what the database admits. A parity case runs both over the same corpus.
  */
-export declare const projectNameSchema: z.ZodString;
-export declare const projectSchema: z.ZodObject<{
-    id: z.ZodString;
-    name: z.ZodString;
-    organization: z.ZodString;
-    status: z.ZodEnum<{
+export declare function projectNameKey(name: string): string;
+export declare const projectSchema: import("zod").ZodObject<{
+    createdAt: import("zod").ZodNullable<import("zod").ZodString>;
+    id: import("zod").ZodString;
+    name: import("zod").ZodString;
+    organization: import("zod").ZodString;
+    status: import("zod").ZodEnum<{
         active: "active";
-        archived: "archived";
         deleted: "deleted";
+        archived: "archived";
     }>;
-    version: z.ZodNumber;
-}, z.core.$strip>;
+    version: import("zod").ZodNumber;
+}, import("zod/v4/core").$strip>;
 export type Project = z.infer<typeof projectSchema>;
 /**
  * One of a project's two environments.
@@ -73,14 +95,14 @@ export type Project = z.infer<typeof projectSchema>;
  * 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<{
+export declare const environmentSchema: import("zod").ZodObject<{
+    id: import("zod").ZodString;
+    kind: import("zod").ZodEnum<{
         test: "test";
         live: "live";
     }>;
-    project: z.ZodString;
-}, z.core.$strip>;
+    project: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
 export type Environment = z.infer<typeof environmentSchema>;
 /**
  * A project together with both of its environments.
@@ -88,27 +110,28 @@ export type Environment = z.infer<typeof environmentSchema>;
  * 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<{
+export declare const provisionedProjectSchema: import("zod").ZodObject<{
+    environments: import("zod").ZodArray<import("zod").ZodObject<{
+        id: import("zod").ZodString;
+        kind: import("zod").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<{
+        project: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
+    project: import("zod").ZodObject<{
+        createdAt: import("zod").ZodNullable<import("zod").ZodString>;
+        id: import("zod").ZodString;
+        name: import("zod").ZodString;
+        organization: import("zod").ZodString;
+        status: import("zod").ZodEnum<{
             active: "active";
-            archived: "archived";
             deleted: "deleted";
+            archived: "archived";
         }>;
-        version: z.ZodNumber;
-    }, z.core.$strip>;
-}, z.core.$strip>;
+        version: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>;
+}, import("zod/v4/core").$strip>;
 export type ProvisionedProject = z.infer<typeof provisionedProjectSchema>;
 /**
  * What a signed-in member is told about a project they may act in.
@@ -120,23 +143,41 @@ export type ProvisionedProject = z.infer<typeof provisionedProjectSchema>;
  * `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.
+ * This remains 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. Lifecycle state and version make an
+ * archived row manageable without making it a valid work target.
  */
-export declare const projectSummarySchema: z.ZodObject<{
-    environmentKinds: z.ZodArray<z.ZodEnum<{
+export declare const projectSummarySchema: import("zod").ZodObject<{
+    createdAt: import("zod").ZodNullable<import("zod").ZodString>;
+    deletionCounts: import("zod").ZodObject<{
+        endpoints: import("zod").ZodNumber;
+        keys: import("zod").ZodNumber;
+        runs: import("zod").ZodNumber;
+        schedules: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>;
+    environmentKinds: import("zod").ZodArray<import("zod").ZodEnum<{
         test: "test";
         live: "live";
     }>>;
-    id: z.ZodString;
-    name: z.ZodString;
-}, z.core.$strip>;
+    id: import("zod").ZodString;
+    name: import("zod").ZodString;
+    status: import("zod").ZodEnum<{
+        active: "active";
+        archived: "archived";
+    }>;
+    version: import("zod").ZodNumber;
+}, import("zod/v4/core").$strip>;
 export type ProjectSummary = z.infer<typeof projectSummarySchema>;
+export declare const projectDeletionCountsSchema: import("zod").ZodObject<{
+    endpoints: import("zod").ZodNumber;
+    keys: import("zod").ZodNumber;
+    runs: import("zod").ZodNumber;
+    schedules: import("zod").ZodNumber;
+}, import("zod/v4/core").$strip>;
+export type ProjectDeletionCounts = z.infer<typeof projectDeletionCountsSchema>;
 /**
- * Every project in the member's organization that they may act in.
+ * Every active or archived project in the member's organization.
  *
  * **Unpaged, with a stated ceiling, because the store beneath it is.**
  * `listProjects` reads an organization's projects in one go; declaring a page
@@ -147,16 +188,29 @@ export type ProjectSummary = z.infer<typeof projectSummarySchema>;
  * 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<{
+export declare const projectListSchema: import("zod").ZodObject<{
+    data: import("zod").ZodArray<import("zod").ZodObject<{
+        createdAt: import("zod").ZodNullable<import("zod").ZodString>;
+        deletionCounts: import("zod").ZodObject<{
+            endpoints: import("zod").ZodNumber;
+            keys: import("zod").ZodNumber;
+            runs: import("zod").ZodNumber;
+            schedules: import("zod").ZodNumber;
+        }, import("zod/v4/core").$strip>;
+        environmentKinds: import("zod").ZodArray<import("zod").ZodEnum<{
             test: "test";
             live: "live";
         }>>;
-        id: z.ZodString;
-        name: z.ZodString;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
+        id: import("zod").ZodString;
+        name: import("zod").ZodString;
+        status: import("zod").ZodEnum<{
+            active: "active";
+            archived: "archived";
+        }>;
+        version: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>>;
+    total: import("zod").ZodNumber;
+}, import("zod/v4/core").$strip>;
 export type ProjectList = z.infer<typeof projectListSchema>;
 /**
  * What a member sends to create a project.
@@ -168,11 +222,31 @@ export type ProjectList = z.infer<typeof projectListSchema>;
  * 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.
+ * There is no `status`: a project is created `active`; archiving is a separate
+ * administrator operation.
  */
-export declare const projectCreateRequestSchema: z.ZodObject<{
-    name: z.ZodString;
-}, z.core.$strip>;
+export declare const projectCreateRequestSchema: import("zod").ZodObject<{
+    name: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
 export type ProjectCreateRequest = z.infer<typeof projectCreateRequestSchema>;
+/** Rename the project without changing its opaque identifier. */
+export declare const projectUpdateRequestSchema: import("zod").ZodObject<{
+    name: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
+export type ProjectUpdateRequest = z.infer<typeof projectUpdateRequestSchema>;
+/** Park or restore the complete project without rewriting its schedules. */
+export declare const projectArchiveRequestSchema: import("zod").ZodObject<{
+    archived: import("zod").ZodBoolean;
+}, import("zod/v4/core").$strip>;
+export type ProjectArchiveRequest = z.infer<typeof projectArchiveRequestSchema>;
+/** What a successful permanent deletion removed. */
+export declare const projectDeletedSchema: import("zod").ZodObject<{
+    deleted: import("zod").ZodLiteral<true>;
+    destroyed: import("zod").ZodObject<{
+        endpoints: import("zod").ZodNumber;
+        keys: import("zod").ZodNumber;
+        runs: import("zod").ZodNumber;
+        schedules: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>;
+}, import("zod/v4/core").$strip>;
+export type ProjectDeleted = z.infer<typeof projectDeletedSchema>;

package/dist/tenancy.js

@@ -1,7 +1,8 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 import { environmentKindSchema } from "./authority.js";
 import { environmentIdSchema, organizationIdSchema, projectIdSchema, } from "./identifiers.js";
 import { versionSchema } from "./protocol.js";
+import { timestampSchema } from "./time.js";
 /**
  * Organizations, projects, and environments.
  *
@@ -33,28 +34,57 @@ export const organizationSchema = z.object({
 /**
  * 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.
+ * `archived` is reversible and stops new work without destroying history.
+ * `deleted` is terminal and exists only while permanent destruction is being
+ * completed; a successful delete removes the project and all of its rows.
  */
 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.
+ * A human label for a project. Mutable, unique within its organization by
+ * `projectNameKey`, 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.
+ * people — which is also why two projects may not share one (FXO-2256): a
+ * switcher with two "Billing reminders" in it is a switcher nobody can use.
  */
 export const projectNameSchema = z
     .string()
     .trim()
     .min(1, "must not be blank")
     .max(120, "must be at most 120 characters");
+/**
+ * How two project names are compared for uniqueness (FXO-2256).
+ *
+ * Per organization, ignoring case and surrounding or repeated spaces:
+ * "Billing reminders" and "billing  Reminders" are one name, which is the
+ * mistake somebody actually makes — retyping a name they already used.
+ *
+ * **Two statements of one rule, kept equal by construction.** The database
+ * computes this key itself, in SQL, on every insert and rename (the triggers
+ * in `apps/api/migrations/0014_project_name_uniqueness.sql`), and a unique
+ * index over it refuses a second active project with the same one — so no
+ * writer can bypass the rule by forgetting a column. This function is the
+ * form's and the store's copy, for a refusal before the request, and it is
+ * deliberately no cleverer than SQLite: case folds for ASCII letters only
+ * (`lower()` there knows no other alphabet), and the whitespace it collapses
+ * is spaces, tabs and newlines. Two names differing only in the case of an
+ * accented letter are two names — an edge stated rather than hidden, because
+ * a rule the form applied and the database did not would refuse in the form
+ * what the database admits. A parity case runs both over the same corpus.
+ */
+export function projectNameKey(name) {
+    return name
+        .replace(/[\t\n\r]/gu, " ")
+        .replace(/ {2,}/gu, " ")
+        .replace(/^ | $/gu, "")
+        .replace(/[A-Z]+/gu, (run) => run.toLowerCase());
+}
 export const projectSchema = z.object({
+    /** Null only for projects created before the control plane recorded dates. */
+    createdAt: timestampSchema.nullable(),
     id: projectIdSchema,
     name: projectNameSchema,
     organization: organizationIdSchema,
@@ -96,21 +126,30 @@ export const provisionedProjectSchema = z.object({
  * `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.
+ * This remains 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. Lifecycle state and version make an
+ * archived row manageable without making it a valid work target.
  */
 export const projectSummarySchema = z.object({
+    createdAt: timestampSchema.nullable(),
+    deletionCounts: z.object({
+        endpoints: z.number().int().nonnegative(),
+        keys: z.number().int().nonnegative(),
+        runs: z.number().int().nonnegative(),
+        schedules: z.number().int().nonnegative(),
+    }),
     environmentKinds: z
         .array(environmentKindSchema)
         .length(2, "a project has exactly two environments"),
     id: projectIdSchema,
     name: projectNameSchema,
+    status: projectStatusSchema.exclude(["deleted"]),
+    version: versionSchema,
 });
+export const projectDeletionCountsSchema = projectSummarySchema.shape.deletionCounts;
 /**
- * Every project in the member's organization that they may act in.
+ * Every active or archived project in the member's organization.
  *
  * **Unpaged, with a stated ceiling, because the store beneath it is.**
  * `listProjects` reads an organization's projects in one go; declaring a page
@@ -125,6 +164,8 @@ export const projectListSchema = z.object({
     data: z
         .array(projectSummarySchema)
         .max(PROJECT_LIST_LIMIT, "more projects than this response can carry; paging is required"),
+    /** Active and archived projects occupy a plan slot; deleted projects do not. */
+    total: z.number().int().nonnegative().max(PROJECT_LIST_LIMIT),
 });
 /**
  * What a member sends to create a project.
@@ -136,10 +177,22 @@ export const projectListSchema = z.object({
  * 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.
+ * There is no `status`: a project is created `active`; archiving is a separate
+ * administrator operation.
  */
 export const projectCreateRequestSchema = z.object({
     name: projectNameSchema,
 });
+/** Rename the project without changing its opaque identifier. */
+export const projectUpdateRequestSchema = z.object({
+    name: projectNameSchema,
+});
+/** Park or restore the complete project without rewriting its schedules. */
+export const projectArchiveRequestSchema = z.object({
+    archived: z.boolean(),
+});
+/** What a successful permanent deletion removed. */
+export const projectDeletedSchema = z.object({
+    deleted: z.literal(true),
+    destroyed: projectDeletionCountsSchema,
+});