@buildinternet/releases-api-types 0.38.0 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-api-types",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "Wire protocol — request/response types for the Releases registry API. Shared by web, workers, and clients.",
   "type": "module",
   "license": "MIT",

package/src/api-types.ts

@@ -334,6 +334,37 @@ export type {
   ReleasesJsonRepo,
   ReleasesJsonRepoRelease,
 } from "./schemas/well-known.js";
+export {
+  ListingValidateBodySchema,
+  ListingActivateBodySchema,
+  ListingIssueSchema,
+  ListingLocationSchema,
+  ListingOrgPointerSchema,
+  ListingValidationResultSchema,
+  ListingActivateResultSchema,
+  ListingClaimBodySchema,
+  ListingClaimVerifyBodySchema,
+  OrgClaimStatusSchema,
+  ClaimMethodSchema,
+  OrgClaimSchema,
+  ClaimCheckOutcomeSchema,
+  ClaimVerifyResultSchema,
+  ListingClaimsResultSchema,
+  type ListingValidateBody,
+  type ListingActivateBody,
+  type ListingIssue,
+  type ListingLocation,
+  type ListingValidationResult,
+  type ListingActivateResult,
+  type ListingClaimBody,
+  type ListingClaimVerifyBody,
+  type OrgClaimStatus,
+  type ClaimMethod,
+  type OrgClaim,
+  type ClaimCheckOutcome,
+  type ClaimVerifyResult,
+  type ListingClaimsResult,
+} from "./schemas/listing.js";
 export {
   SourceListItemSchema,
   SourceWithOrgSchema,

package/src/schemas/listing.ts

@@ -0,0 +1,138 @@
+import { z } from "zod";
+
+/**
+ * Public wire contract for the self-serve listing lane (#1947 phase 2):
+ * POST /v1/listing/validate and POST /v1/listing/activate. This projection is
+ * deliberately independent of the internal materialization plan — it is the
+ * stable shape web/CLI consume while internals stay free to change.
+ */
+
+export const ListingValidateBodySchema = z.strictObject({
+  domain: z.string().min(1).max(255),
+});
+export type ListingValidateBody = z.infer<typeof ListingValidateBodySchema>;
+
+export const ListingActivateBodySchema = z.strictObject({
+  domain: z.string().min(1).max(255),
+  requestTracking: z.boolean().optional(),
+});
+export type ListingActivateBody = z.infer<typeof ListingActivateBodySchema>;
+
+export const ListingIssueSchema = z.strictObject({
+  path: z.string(),
+  message: z.string(),
+});
+export type ListingIssue = z.infer<typeof ListingIssueSchema>;
+
+export const ListingLocationSchema = z.strictObject({
+  /** The declared locator value (feed URL, github ref, url, appstore id, file). */
+  locator: z.string(),
+  kind: z.enum(["feed", "github", "appstore", "url", "file"]),
+  classification: z.enum(["tier1-live", "tier2-paused-review"]),
+  /** Plain-English "what this becomes" for the preview UI. */
+  becomes: z.string(),
+  /** Present when the locator is nested under a manifest product. */
+  productName: z.string().optional(),
+});
+export type ListingLocation = z.infer<typeof ListingLocationSchema>;
+
+export const ListingOrgPointerSchema = z.strictObject({
+  slug: z.string(),
+  name: z.string(),
+  webUrl: z.string(),
+});
+export type ListingOrgPointer = z.infer<typeof ListingOrgPointerSchema>;
+
+export const ListingValidationResultSchema = z.strictObject({
+  valid: z.boolean(),
+  errors: z.array(ListingIssueSchema),
+  domainStatus: z.enum(["unlisted", "listed", "stub"]),
+  /** Present when domainStatus is "listed" or "stub". */
+  org: ListingOrgPointerSchema.optional(),
+  /** Present when valid: identity fields as they would land. */
+  identity: z
+    .strictObject({
+      name: z.string(),
+      slug: z.string(),
+      domain: z.string(),
+    })
+    .optional(),
+  products: z.array(z.strictObject({ name: z.string(), locationCount: z.number() })).optional(),
+  locations: z.array(ListingLocationSchema),
+});
+export type ListingValidationResult = z.infer<typeof ListingValidationResultSchema>;
+
+export const ListingActivateResultSchema = z.strictObject({
+  /** True when this call created the stub; false for the existing-stub carve-out. */
+  activated: z.boolean(),
+  org: z.strictObject({
+    slug: z.string(),
+    name: z.string(),
+    status: z.enum(["stub", "tracked"]),
+    webUrl: z.string(),
+  }),
+  trackingRequested: z.boolean(),
+});
+export type ListingActivateResult = z.infer<typeof ListingActivateResultSchema>;
+
+/**
+ * Ownership claim flow (#1947 epic item 2): a signed-in user proves control
+ * of a listed domain via a well-known token file OR a DNS TXT record.
+ */
+
+export const ListingClaimBodySchema = z.strictObject({
+  domain: z.string().min(1).max(255),
+});
+export type ListingClaimBody = z.infer<typeof ListingClaimBodySchema>;
+
+export const ListingClaimVerifyBodySchema = z.strictObject({
+  claimId: z.string().min(1),
+});
+export type ListingClaimVerifyBody = z.infer<typeof ListingClaimVerifyBodySchema>;
+
+export const OrgClaimStatusSchema = z.enum(["pending", "verified", "expired"]);
+export type OrgClaimStatus = z.infer<typeof OrgClaimStatusSchema>;
+
+export const ClaimMethodSchema = z.enum(["well-known", "dns-txt"]);
+export type ClaimMethod = z.infer<typeof ClaimMethodSchema>;
+
+/**
+ * `token` + `instructions` are only present while the claim is `pending` (or
+ * on mint) — once verified there's nothing left to prove, and an expired
+ * claim's token is stale.
+ */
+export const OrgClaimSchema = z.strictObject({
+  id: z.string(),
+  org: ListingOrgPointerSchema,
+  status: OrgClaimStatusSchema,
+  method: ClaimMethodSchema.optional(),
+  token: z.string().optional(),
+  createdAt: z.string(),
+  verifiedAt: z.string().optional(),
+  expiresAt: z.string(),
+  instructions: z
+    .strictObject({
+      wellKnownUrl: z.string(),
+      dnsRecordName: z.string(),
+    })
+    .optional(),
+});
+export type OrgClaim = z.infer<typeof OrgClaimSchema>;
+
+export const ClaimCheckOutcomeSchema = z.enum(["ok", "mismatch", "unreachable"]);
+export type ClaimCheckOutcome = z.infer<typeof ClaimCheckOutcomeSchema>;
+
+export const ClaimVerifyResultSchema = z.strictObject({
+  verified: z.boolean(),
+  checked: z.strictObject({
+    wellKnown: ClaimCheckOutcomeSchema,
+    dnsTxt: ClaimCheckOutcomeSchema,
+  }),
+  claim: OrgClaimSchema,
+});
+export type ClaimVerifyResult = z.infer<typeof ClaimVerifyResultSchema>;
+
+export const ListingClaimsResultSchema = z.strictObject({
+  claims: z.array(OrgClaimSchema),
+});
+export type ListingClaimsResult = z.infer<typeof ListingClaimsResultSchema>;

package/src/schemas/orgs.ts

@@ -38,6 +38,12 @@ export const OrgListItemSchema = z.object({
   lastActivity: z.string().nullable(),
   topProducts: z.array(z.string()),
   sparkline: z.array(z.number().int().min(0)).length(30),
+  /**
+   * Additive, admin-only field (#1947 phase 2). Only populated on the
+   * `GET /v1/orgs?trackingRequested=1` demand-queue projection — absent on
+   * the public catalog listing.
+   */
+  trackingRequestedAt: z.string().nullable().optional(),
 });
 
 /**

package/src/schemas/sources.ts

@@ -171,6 +171,8 @@ export const SourceDetailSchema = z.object({
   latestDate: z.string().nullable(),
   lastFetchedAt: z.string().nullable(),
   lastPolledAt: z.string().nullable(),
+  // #1969: additive so pinned old workers/clients degrade gracefully.
+  changeDetectedAt: z.string().nullable().optional(),
   trackingSince: z.string(),
   releases: z.array(ReleaseItemSchema),
   pagination: SourceFeedPaginationSchema,