@buildinternet/releases-api-types 0.39.0 → 0.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-api-types",
-  "version": "0.39.0",
+  "version": "0.41.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

@@ -342,12 +342,36 @@ export {
   ListingOrgPointerSchema,
   ListingValidationResultSchema,
   ListingActivateResultSchema,
+  ListingClaimBodySchema,
+  ListingClaimVerifyBodySchema,
+  OrgClaimStatusSchema,
+  ClaimMethodSchema,
+  OrgClaimSchema,
+  ClaimCheckOutcomeSchema,
+  ClaimVerifyResultSchema,
+  ListingClaimsResultSchema,
+  ListingPromoteBodySchema,
+  ListingPromoteLocatorOutcomeSchema,
+  ListingPromoteLocatorSchema,
+  ListingPromoteResultSchema,
   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,
+  type ListingPromoteBody,
+  type ListingPromoteLocatorOutcome,
+  type ListingPromoteLocator,
+  type ListingPromoteResult,
 } from "./schemas/listing.js";
 export {
   SourceListItemSchema,

package/src/schemas/listing.ts

@@ -74,3 +74,97 @@ export const ListingActivateResultSchema = z.strictObject({
   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>;
+
+/**
+ * Self-serve Tier-1 promotion (#1947 epic item 3, PR B): a verified owner
+ * promotes their claimed stub to `tracked`. Independent of the internal
+ * materialization plan — this is the stable public projection.
+ */
+
+export const ListingPromoteBodySchema = z.strictObject({
+  domain: z.string().min(1).max(255),
+});
+export type ListingPromoteBody = z.infer<typeof ListingPromoteBodySchema>;
+
+export const ListingPromoteLocatorOutcomeSchema = z.enum(["live", "queued-for-review"]);
+export type ListingPromoteLocatorOutcome = z.infer<typeof ListingPromoteLocatorOutcomeSchema>;
+
+export const ListingPromoteLocatorSchema = z.strictObject({
+  locator: z.string(),
+  outcome: ListingPromoteLocatorOutcomeSchema,
+});
+export type ListingPromoteLocator = z.infer<typeof ListingPromoteLocatorSchema>;
+
+export const ListingPromoteResultSchema = z.strictObject({
+  promoted: z.boolean(),
+  /** Present and true only for the idempotent already-`tracked` no-op. */
+  alreadyTracked: z.boolean().optional(),
+  sources: z.strictObject({
+    created: z.number(),
+    matched: z.number(),
+  }),
+  locators: z.array(ListingPromoteLocatorSchema),
+});
+export type ListingPromoteResult = z.infer<typeof ListingPromoteResultSchema>;

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,

package/src/schemas/well-known.test.ts

@@ -41,6 +41,7 @@ describe("releases.json v2 schemas", () => {
           docs: "https://docs.acme.com/cloud",
           support: "https://acme.com/support",
           social: { twitter: "acmecloud" },
+          tags: ["ci", "cloud"],
           archived: true,
           releases: [{ github: "acme/cloud", canonical: true }],
         },
@@ -56,9 +57,33 @@ describe("releases.json v2 schemas", () => {
     });
 
     expect(parsed.products?.[0]?.kind).toBe("future-kind");
+    expect(parsed.products?.[0]?.tags).toEqual(["ci", "cloud"]);
     expect(parsed.registries?.["example.com"]).toEqual({ anything: "goes" });
   });
 
+  it("accepts product-level tags and enforces the same bounds as org tags", () => {
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        products: [{ name: "Cloud", tags: ["analytics", "sdk"] }],
+      }).success,
+    ).toBe(true);
+    // too many tags (> 50)
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        products: [{ name: "Cloud", tags: Array.from({ length: 51 }, (_, i) => `tag-${i}`) }],
+      }).success,
+    ).toBe(false);
+    // empty tag string
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        products: [{ name: "Cloud", tags: [""] }],
+      }).success,
+    ).toBe(false);
+  });
+
   it("accepts the repo variant including github self", () => {
     expect(
       ReleasesJsonRepoSchema.safeParse({
@@ -70,6 +95,21 @@ describe("releases.json v2 schemas", () => {
     ).toBe(true);
   });
 
+  it("requires https for locator URLs and avatar", () => {
+    expect(
+      ReleasesJsonDomainSchema.safeParse({ version: 2, releases: [{ url: "https://acme.com/x" }] })
+        .success,
+    ).toBe(true);
+    expect(
+      ReleasesJsonDomainSchema.safeParse({ version: 2, releases: [{ url: "http://acme.com/x" }] })
+        .success,
+    ).toBe(false);
+    expect(
+      ReleasesJsonDomainSchema.safeParse({ version: 2, avatar: "http://acme.com/logo.png" })
+        .success,
+    ).toBe(false);
+  });
+
   it("requires the version 2 literal with no v1 compatibility", () => {
     expect(ReleasesJsonConfigSchema.safeParse({ releases: [location(1)] }).success).toBe(false);
     expect(ReleasesJsonConfigSchema.safeParse({ version: 1 }).success).toBe(false);

package/src/schemas/well-known.ts

@@ -8,9 +8,14 @@ const MAX_FILE_RELEASES = 32;
 const SocialValueSchema = z.string().min(1).max(200);
 const SocialSchema = z.record(z.string().min(1).max(40), SocialValueSchema);
 
-const HttpsUrlSchema = z
-  .url()
-  .refine((url) => url.startsWith("https://"), "locator must be an https URL");
+// `z.url().startsWith(...)` keeps the runtime URL + https check AND serializes to
+// JSON Schema as `format: "uri"` + `pattern: "^https://"` — so the generated
+// public schema rejects non-https schemes too (a plain `.refine()` would be
+// silently dropped by z.toJSONSchema).
+const HttpsUrlSchema = z.url().startsWith("https://", "locator must be an https URL");
+
+/** Shared tag-array bounds — kept identical for org-level and product-level tags. */
+const TagsSchema = z.array(z.string().min(1).max(60)).max(50);
 
 const ReleaseLocationFields = {
   url: HttpsUrlSchema.optional(),
@@ -87,6 +92,7 @@ export const ReleasesJsonProductSchema = z.strictObject({
   docs: z.url().optional(),
   support: z.url().optional(),
   social: SocialSchema.optional(),
+  tags: TagsSchema.optional(),
   archived: z.boolean().optional(),
   releases: DomainProductReleasesSchema.optional(),
 });
@@ -138,7 +144,7 @@ export const ReleasesJsonDomainSchema = z
     description: z.string().max(2000).optional(),
     category: z.string().min(1).max(120).optional(),
     avatar: HttpsUrlSchema.optional(),
-    tags: z.array(z.string().min(1).max(60)).max(50).optional(),
+    tags: TagsSchema.optional(),
     social: SocialSchema.optional(),
     products: z.array(ReleasesJsonProductSchema).max(MAX_PRODUCTS).optional(),
   })
@@ -184,7 +190,7 @@ export const CreateStubOrgBodySchema = z.strictObject({
   description: z.string().max(2000).optional(),
   category: z.string().min(1).max(120).optional(),
   avatar: HttpsUrlSchema.optional(),
-  tags: z.array(z.string().min(1).max(60)).max(50).optional(),
+  tags: TagsSchema.optional(),
   social: SocialSchema.optional(),
   products: z.array(ReleasesJsonProductSchema).max(MAX_PRODUCTS).optional(),
   releases: DomainReleasesSchema.optional(),