@buildinternet/releases-api-types 0.37.0 → 0.39.0

package/package.json

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

@@ -24,6 +24,8 @@ import type {
   ReleaseSummaryItemSchema,
   OverviewPageItemSchema,
   OverviewCitationSchema,
+  OrgStatusSchema,
+  ReleaseLocationItemSchema,
 } from "./schemas/shared.js";
 import type {
   OrgListItemSchema,
@@ -263,6 +265,8 @@ export {
   ReleaseSummaryItemSchema,
   OverviewPageItemSchema,
   OverviewCitationSchema,
+  OrgStatusSchema,
+  ReleaseLocationItemSchema,
   CategorySchema,
   NoticeSchema,
 } from "./schemas/shared.js";
@@ -308,6 +312,8 @@ export {
   WorkspaceProfileResponseSchema,
 } from "./schemas/account-profile.js";
 export {
+  CreateStubOrgBodySchema,
+  StubFromDomainBodySchema,
   ReleasesJsonConfigSchema,
   ReleasesJsonDomainReleaseSchema,
   ReleasesJsonDomainSchema,
@@ -319,6 +325,8 @@ export {
   SyncWellKnownResponseSchema,
 } from "./schemas/well-known.js";
 export type {
+  CreateStubOrgBody,
+  StubFromDomainBody,
   ReleasesJsonConfig,
   ReleasesJsonDomain,
   ReleasesJsonDomainRelease,
@@ -326,6 +334,21 @@ export type {
   ReleasesJsonRepo,
   ReleasesJsonRepoRelease,
 } from "./schemas/well-known.js";
+export {
+  ListingValidateBodySchema,
+  ListingActivateBodySchema,
+  ListingIssueSchema,
+  ListingLocationSchema,
+  ListingOrgPointerSchema,
+  ListingValidationResultSchema,
+  ListingActivateResultSchema,
+  type ListingValidateBody,
+  type ListingActivateBody,
+  type ListingIssue,
+  type ListingLocation,
+  type ListingValidationResult,
+  type ListingActivateResult,
+} from "./schemas/listing.js";
 export {
   SourceListItemSchema,
   SourceWithOrgSchema,
@@ -522,6 +545,11 @@ export type { ResolveResponse } from "./schemas/resolve.js";
 
 export type MediaItem = z.infer<typeof MediaItemSchema>;
 
+// ── Stub tier (#1947) ──
+
+export type OrgStatus = z.infer<typeof OrgStatusSchema>;
+export type ReleaseLocationItem = z.infer<typeof ReleaseLocationItemSchema>;
+
 // ── Stats ──
 
 export type Stats = z.infer<typeof StatsSchema>;

package/src/schemas/listing.ts

@@ -0,0 +1,76 @@
+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>;

package/src/schemas/lookups.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { KIND_VALUES } from "@buildinternet/releases-core/kinds";
-import { CategorySchema } from "./shared.js";
+import { CategorySchema, OrgStatusSchema, ReleaseLocationItemSchema } from "./shared.js";
 
 /**
  * Status flags returned by `POST /v1/lookups`:
@@ -104,6 +104,14 @@ export const DomainLookupOrgSchema = z.object({
   category: z.string().nullable(),
   avatarUrl: z.string().nullable(),
   matchedVia: z.enum(["primary", "alias"]),
+  /** Org tier (#1947). Optional for mid-deploy tolerance; absent ⇒ `"tracked"`. */
+  status: OrgStatusSchema.optional(),
+  /**
+   * Declared release locations (#1947) for a stub org — the "check these
+   * locations" answer when the domain resolves to an org with no sources yet.
+   * Omitted/empty for a tracked org.
+   */
+  locations: z.array(ReleaseLocationItemSchema).optional(),
 });
 
 export const DomainLookupProductSchema = z.object({

package/src/schemas/orgs.ts

@@ -6,9 +6,11 @@ import {
   CategorySchema,
   ListResponseSchema,
   NoticeSchema,
+  OrgStatusSchema,
   OverviewPageItemSchema,
   PaginationSchema,
   ReleaseItemSchema,
+  ReleaseLocationItemSchema,
   VideoSourceInfoSchema,
 } from "./shared.js";
 import { SourceListItemSchema } from "./sources.js";
@@ -24,12 +26,24 @@ export const OrgListItemSchema = z.object({
   category: CategorySchema.nullable(),
   avatarUrl: z.string().nullable(),
   featured: z.boolean(),
+  /**
+   * Org tier (#1947). Optional for mid-deploy tolerance; absent ⇒ `"tracked"`.
+   * A `"stub"` org has no processed sources yet — the UI renders a badge and a
+   * stub is excluded from release-ranked surfaces.
+   */
+  status: OrgStatusSchema.optional(),
   sourceCount: z.number().int().min(0),
   releaseCount: z.number().int().min(0),
   recentReleaseCount: z.number().int().min(0),
   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(),
 });
 
 /**
@@ -480,6 +494,18 @@ export const OrgDetailSchema = z.object({
   fetchPaused: z.boolean().optional(),
   /** How the org row was created. `on_demand` orgs are excluded from overview generation regardless of `autoGenerateContent`. */
   discovery: z.enum(["curated", "agent", "on_demand"]).optional(),
+  /**
+   * Org tier (#1947). Optional for mid-deploy tolerance; absent ⇒ `"tracked"`.
+   * A `"stub"` org's `sources` array is empty — `locations` carries the declared
+   * release locations instead.
+   */
+  status: OrgStatusSchema.optional(),
+  /**
+   * Declared release locations (#1947), present (and non-empty) for stub orgs.
+   * Same shape as a releases.json `releases[]` entry plus `basis`/`sourceId`.
+   * Omitted or empty for a tracked org with no locators.
+   */
+  locations: z.array(ReleaseLocationItemSchema).optional(),
   tags: z.array(z.string()).optional(),
   sourceCount: z.number().int().min(0),
   releaseCount: z.number().int().min(0),

package/src/schemas/overviews.ts

@@ -11,23 +11,19 @@ export const OrgOverviewResponseSchema = OverviewPageItemSchema.extend({
 }).nullable();
 
 /**
- * Incoming citation row attached to `POST /v1/orgs/:slug/overview`. Slimmer
- * than the read-side `OverviewCitationSchema` because the wire shape doesn't
- * carry `releaseId` — that's resolved server-side from `sourceUrl`. Spans
- * must be in-range (`endIndex > startIndex`); the cross-field
- * `endIndex <= content.length` check stays in the handler.
+ * Incoming citation row attached to `POST /v1/orgs/:slug/overview`. A source the
+ * overview drew on — just `sourceUrl` (+ optional display `title`); `releaseId`
+ * is resolved server-side from `sourceUrl`. The legacy body-offset fields
+ * (`startIndex`/`endIndex`/`citedText`) are accepted-but-ignored for wire
+ * back-compat with older clients (#1934); they're no longer stored.
  */
-export const IncomingOverviewCitationSchema = z
-  .object({
-    startIndex: z.number().int().min(0),
-    endIndex: z.number().int().min(1),
-    sourceUrl: z.string().min(1),
-    title: z.string().nullable().optional(),
-    citedText: z.string().min(1),
-  })
-  .refine((c) => c.endIndex > c.startIndex, {
-    message: "endIndex must be > startIndex",
-  });
+export const IncomingOverviewCitationSchema = z.object({
+  sourceUrl: z.string().min(1),
+  title: z.string().nullable().optional(),
+  startIndex: z.number().int().min(0).optional(),
+  endIndex: z.number().int().min(0).optional(),
+  citedText: z.string().optional(),
+});
 
 /**
  * Body accepted by `POST /v1/orgs/:slug/overview` — the agent-authored

package/src/schemas/shared.ts

@@ -44,6 +44,37 @@ export const VideoSourceInfoSchema = z.object({
   provider: z.enum(["youtube", "vimeo", "wistia"]),
 });
 
+/**
+ * Org tier surfaced on read paths (#1947). `stub` = known only by declared
+ * release locations (no processed sources yet); `tracked` = a normal org whose
+ * sources fetch. The column is `organizations.tier`; the wire name is `status`.
+ * Optional on the wire so a pinned client mid-deploy tolerates its absence —
+ * treat a missing value as `"tracked"`.
+ */
+export const OrgStatusSchema = z.enum(["stub", "tracked"]);
+
+/**
+ * A declared release location (#1947) — one `release_locations` row on the
+ * wire, the same shape a releases.json `releases[]` entry carries plus its
+ * provenance `basis` and, once promoted, the `sourceId` it materialized into.
+ * Surfaced on stub orgs so an agent gets "release info is published at these
+ * locations" instead of an empty sources list.
+ */
+export const ReleaseLocationItemSchema = z.object({
+  url: z.string().optional(),
+  feed: z.string().optional(),
+  github: z.string().optional(),
+  appstore: z.string().optional(),
+  file: z.string().optional(),
+  title: z.string().nullable().optional(),
+  canonical: z.boolean(),
+  basis: z.enum(["curator", "declared", "detected", "generated"]),
+  /** Owning product id when the locator is product-scoped, else null. */
+  productId: z.string().nullable(),
+  /** Set once the locator has been promoted into a source, else null. */
+  sourceId: z.string().nullable(),
+});
+
 export const PaginationSchema = z.object({
   page: z.number().int().min(1),
   pageSize: z.number().int().min(1),
@@ -146,19 +177,32 @@ export const ReleaseSummaryItemSchema = z.object({
 });
 
 /**
- * Inline citation attached to an overview page (#846). Each row maps a
- * character span in `OverviewPageItem.content` back to a release URL the
- * model cited via Anthropic's search_result blocks. Optional everywhere it
- * appears — pages generated before #846 lands have none, and consumers
- * should degrade gracefully.
+ * A source attached to an overview page (#846, reshaped #1934). Each row names
+ * a source the overview drew on — `sourceUrl` plus, when it resolved to an
+ * on-registry release, `releaseId` + a canonical `releaseWebUrl`. This is a
+ * source *list*, not span-anchored provenance: the old body char offsets +
+ * verbatim quote are removed. Optional everywhere it appears — consumers should
+ * degrade gracefully.
  */
 export const OverviewCitationSchema = z.object({
-  startIndex: z.number().int().min(0),
-  endIndex: z.number().int().min(0),
   sourceUrl: z.string(),
   title: z.string().nullable().optional(),
-  citedText: z.string(),
+  /** Best-effort link to the on-registry release this source maps to (resolved server-side). */
   releaseId: z.string().nullable().optional(),
+  /**
+   * Canonical web URL of the on-registry release page for this source, when
+   * `releaseId` resolved (#1934). The Sources footer links here (internal,
+   * crawlable) in preference to the external `sourceUrl`.
+   */
+  releaseWebUrl: z.string().nullable().optional(),
+  /**
+   * @deprecated Body char offsets / verbatim quote — removed with span-anchored
+   * citations (#1934). Kept optional for wire back-compat; no producer emits
+   * them and no consumer should read them.
+   */
+  startIndex: z.number().int().min(0).optional(),
+  endIndex: z.number().int().min(0).optional(),
+  citedText: z.string().optional(),
 });
 
 /**

package/src/schemas/well-known.ts

@@ -168,6 +168,41 @@ export type ReleasesJsonProduct = z.infer<typeof ReleasesJsonProductSchema>;
 export type ReleasesJsonDomainRelease = z.infer<typeof ReleasesJsonDomainReleaseSchema>;
 export type ReleasesJsonRepoRelease = z.infer<typeof ReleasesJsonRepoReleaseSchema>;
 
+/**
+ * Body for `POST /v1/orgs/stub` — curator-authored stub org (#1947). Mirrors
+ * the domain-manifest identity + product + locator shape (so a curator can hand
+ * the same declaration a manifest would carry), minus manifest-transport fields
+ * (`version`/`$schema`/`registries`) and plus the registry-identity fields a
+ * stub org needs to be resolvable (`slug`/`domain`). Locators are optional — an
+ * identity-only stub (locations TBD) is valid. `category`/taxonomy strings stay
+ * lenient; the route resolves them and ignores the rest, same as the reconciler.
+ */
+export const CreateStubOrgBodySchema = z.strictObject({
+  name: z.string().min(1).max(120),
+  slug: z.string().min(1).max(120).optional(),
+  domain: z.string().min(1).max(255).optional(),
+  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(),
+  social: SocialSchema.optional(),
+  products: z.array(ReleasesJsonProductSchema).max(MAX_PRODUCTS).optional(),
+  releases: DomainReleasesSchema.optional(),
+});
+
+export type CreateStubOrgBody = z.infer<typeof CreateStubOrgBodySchema>;
+
+/**
+ * Body for `POST /v1/orgs/stub-from-domain` (#1947) — the unlisted-domain path.
+ * The worker fetches https://{domain}/.well-known/releases.json and, if valid
+ * and the domain has no org yet, creates a stub org + declared locators.
+ */
+export const StubFromDomainBodySchema = z.strictObject({
+  domain: z.string().min(1).max(255),
+});
+
+export type StubFromDomainBody = z.infer<typeof StubFromDomainBodySchema>;
+
 /** Response shape of POST /v1/orgs/:slug/sync-well-known. */
 export const SyncWellKnownResponseSchema = z.object({
   fetched: z.boolean(),