@buildinternet/releases-api-types 0.57.1 → 0.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-api-types",
-  "version": "0.57.1",
+  "version": "0.58.0",
   "description": "Wire protocol — request/response types for the Releases registry API. Shared by web, workers, and clients.",
   "type": "module",
   "license": "MIT",
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@buildinternet/releases-core": "^0.34.0",
+    "@buildinternet/releases-core": "^0.35.0",
     "zod": "^4.4.3"
   },
   "publishConfig": {

package/src/api-types.ts

@@ -396,6 +396,7 @@ export {
   ListingValidateBodySchema,
   ListingActivateBodySchema,
   ListingIssueSchema,
+  ListingSetupStepSchema,
   ListingLocationSchema,
   ListingOrgPointerSchema,
   ListingValidationResultSchema,
@@ -419,6 +420,7 @@ export {
   type ListingValidateBody,
   type ListingActivateBody,
   type ListingIssue,
+  type ListingSetupStep,
   type ListingLocation,
   type ListingValidationResult,
   type ListingActivateResult,

package/src/schemas/listing.ts

@@ -24,15 +24,27 @@ export const ListingIssueSchema = z.strictObject({
 });
 export type ListingIssue = z.infer<typeof ListingIssueSchema>;
 
+/** One follow-up the owner takes after declaring `publish: "push"`. */
+export const ListingSetupStepSchema = z.strictObject({
+  id: z.enum(["verify", "token", "action"]),
+  title: z.string(),
+  detail: z.string(),
+});
+export type ListingSetupStep = z.infer<typeof ListingSetupStepSchema>;
+
 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"]),
+  kind: z.enum(["feed", "github", "appstore", "url", "file", "push"]),
+  classification: z.enum(["tier1-live", "tier2-paused-review", "push-setup"]),
   /** 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(),
+  /** Changelog file or glob. Present on `kind: "push"`. */
+  path: z.string().optional(),
+  /** Present on `kind: "push"`: verify ownership, mint a token, add the Action. */
+  setupSteps: z.array(ListingSetupStepSchema).optional(),
 });
 export type ListingLocation = z.infer<typeof ListingLocationSchema>;
 

package/src/schemas/shared.ts

@@ -87,6 +87,10 @@ export const ReleaseLocationItemSchema = z.object({
   productId: z.string().nullable(),
   /** Set once the locator has been promoted into a source, else null. */
   sourceId: z.string().nullable(),
+  /** `"push"` when the owner publishes this changelog instead of us polling it. */
+  publish: z.literal("push").optional(),
+  /** Changelog file or glob. Present with `publish: "push"`. */
+  path: z.string().optional(),
 });
 
 export const PaginationSchema = z.object({

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

@@ -122,6 +122,67 @@ describe("releases.json v2 schemas", () => {
     ).toBe(false);
   });
 
+  it("accepts a push-publish locator on github + path", () => {
+    expect(
+      ReleasesJsonDomainSchema.parse({
+        version: 2,
+        releases: [
+          { github: "acme/docs", path: "changelog/**/*.mdx", publish: "push", title: "Docs" },
+        ],
+      }),
+    ).toEqual({
+      version: 2,
+      releases: [
+        { github: "acme/docs", path: "changelog/**/*.mdx", publish: "push", title: "Docs" },
+      ],
+    });
+    expect(
+      ReleasesJsonRepoSchema.safeParse({
+        version: 2,
+        releases: [{ github: "self", path: "CHANGELOG.md", publish: "push" }],
+      }).success,
+    ).toBe(true);
+  });
+
+  it("rejects an incomplete or unsafe push-publish locator", () => {
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        releases: [{ github: "acme/docs", publish: "push" }],
+      }).success,
+    ).toBe(false);
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        releases: [{ path: "CHANGELOG.md", publish: "push" }],
+      }).success,
+    ).toBe(false);
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        releases: [{ github: "acme/docs", path: "CHANGELOG.md" }],
+      }).success,
+    ).toBe(false);
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        releases: [{ github: "acme/docs", path: "CHANGELOG.md", publish: "poll" }],
+      }).success,
+    ).toBe(false);
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        releases: [{ github: "acme/docs", path: "../secrets", publish: "push" }],
+      }).success,
+    ).toBe(false);
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        releases: [{ github: "acme/docs", path: "/etc/passwd", publish: "push" }],
+      }).success,
+    ).toBe(false);
+  });
+
   it("allows github self only in repo files", () => {
     expect(
       ReleasesJsonDomainSchema.safeParse({ version: 2, releases: [{ github: "self" }] }).success,

package/src/schemas/well-known.ts

@@ -17,6 +17,19 @@ const HttpsUrlSchema = z.url().startsWith("https://", "locator must be an https
 /** 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);
 
+/**
+ * Changelog file or glob inside the declared repo (Action `changelog-path` /
+ * `changelog-glob`). Relative only — no scheme, no leading slash, no `..`.
+ */
+const PublishPathSchema = z
+  .string()
+  .min(1)
+  .max(200)
+  .regex(
+    /^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$))[A-Za-z0-9._~@%+\-/*?[\]{}]+$/,
+    "path must be a relative changelog file or glob",
+  );
+
 const ReleaseLocationFields = {
   url: HttpsUrlSchema.optional(),
   feed: HttpsUrlSchema.optional(),
@@ -24,6 +37,13 @@ const ReleaseLocationFields = {
   file: HttpsUrlSchema.optional(),
   title: z.string().min(1).max(200).optional(),
   canonical: z.boolean().optional(),
+  /**
+   * `"push"` means the owner publishes this changelog (GitHub Action / publish
+   * token) instead of us polling it. Requires `github` + `path`.
+   */
+  publish: z.literal("push").optional(),
+  /** Required with `publish: "push"`. The file or glob the Action watches. */
+  path: PublishPathSchema.optional(),
 };
 
 function hasLocator(value: {
@@ -36,6 +56,12 @@ function hasLocator(value: {
   return Boolean(value.url || value.feed || value.github || value.appstore || value.file);
 }
 
+/** `publish: "push"` is a mode on a github locator, not a locator by itself. */
+function pushPublishComplete(value: { github?: string; publish?: "push"; path?: string }): boolean {
+  if (value.publish === "push") return Boolean(value.github && value.path);
+  return value.path === undefined;
+}
+
 /** A domain manifest can name a concrete GitHub repository, but never `self`. */
 export const ReleasesJsonDomainReleaseSchema = z
   .strictObject({
@@ -45,7 +71,11 @@ export const ReleasesJsonDomainReleaseSchema = z
       .regex(/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/, "github must be owner/repo")
       .optional(),
   })
-  .refine(hasLocator, "at least one release locator is required");
+  .refine(hasLocator, "at least one release locator is required")
+  .refine(
+    pushPublishComplete,
+    'publish: "push" requires github (owner/repo) and path (changelog file or glob)',
+  );
 
 /** A repo manifest additionally accepts `github: "self"`. */
 export const ReleasesJsonRepoReleaseSchema = z
@@ -58,7 +88,11 @@ export const ReleasesJsonRepoReleaseSchema = z
       ])
       .optional(),
   })
-  .refine(hasLocator, "at least one release locator is required");
+  .refine(hasLocator, "at least one release locator is required")
+  .refine(
+    pushPublishComplete,
+    'publish: "push" requires github (owner/repo or "self") and path (changelog file or glob)',
+  );
 
 function releasesArray<T extends z.ZodType>(item: T, max: number) {
   return z