@ozzylabs/feedradar 0.1.4 → 0.1.6

package/dist/schemas/source.d.ts

@@ -5,6 +5,8 @@ export declare const SourceKindSchema: z.ZodEnum<{
     "html-js": "html-js";
     "github-releases": "github-releases";
     "npm-registry": "npm-registry";
+    "json-feed": "json-feed";
+    "json-api": "json-api";
 }>;
 export type SourceKind = z.infer<typeof SourceKindSchema>;
 /**
@@ -125,6 +127,180 @@ export declare const SourceJsOptionsSchema: z.ZodObject<{
     userAgent: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type SourceJsOptions = z.infer<typeof SourceJsOptionsSchema>;
+/**
+ * HTTP options for `kind: json-api` sources (ADR-0012 §D2).
+ *
+ * Phase 1 supports GET only. `headers` accepts arbitrary key/value pairs and
+ * supports `${VAR}` env-var interpolation (resolved by the adapter, never
+ * persisted to log / frontmatter — see ADR-0012 §D5c).
+ *
+ * The schema deliberately does not validate header values against env names —
+ * the adapter handles unresolved `${VAR}` placeholders by omitting the header
+ * (degraded fetch). This lets public APIs work without env wiring while
+ * authenticated APIs fail-fast with a 401/403 at runtime.
+ */
+export declare const SourceHttpOptionsSchema: z.ZodObject<{
+    method: z.ZodDefault<z.ZodLiteral<"GET">>;
+    headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export type SourceHttpOptions = z.infer<typeof SourceHttpOptionsSchema>;
+/**
+ * Pagination configuration for `kind: json-api` sources (ADR-0012 §D2).
+ *
+ * Five wire formats are supported:
+ *
+ *   page         — `?page=K&pageSize=N` (e.g. AWS What's New, dev.to)
+ *   offset       — `?offset=K&limit=N`
+ *   cursor       — `?after=<cursorValue>` with `nextCursor` extracted via JSONPath
+ *   link-header  — `Link: <...>; rel="next"` HTTP header
+ *   token        — `?pageToken=<opaque>` opaque continuation token
+ *   none         — single request, no pagination
+ *
+ * `maxPages` is a hard cap to prevent runaway loops / DoS on misconfigured
+ * recipes. The default (20) matches a conservative bound for normal-mode
+ * fetching; `--backfill` can override via `--max-pages` to walk further.
+ *
+ * `nextCursorPath` / `totalPath` are JSONPath-lite expressions resolved against
+ * the parsed response body. `totalPath` is consulted in backfill mode to
+ * compute an upper bound on pages and short-circuit early when the total is
+ * known.
+ */
+export declare const SourcePaginationSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        page: "page";
+        offset: "offset";
+        cursor: "cursor";
+        "link-header": "link-header";
+        token: "token";
+        none: "none";
+    }>;
+    param: z.ZodOptional<z.ZodString>;
+    start: z.ZodOptional<z.ZodNumber>;
+    pageSize: z.ZodOptional<z.ZodNumber>;
+    pageSizeParam: z.ZodOptional<z.ZodString>;
+    nextCursorPath: z.ZodOptional<z.ZodString>;
+    totalPath: z.ZodOptional<z.ZodString>;
+    maxPages: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type SourcePagination = z.infer<typeof SourcePaginationSchema>;
+/**
+ * Selector ruleset for `kind: json-api` sources (ADR-0012 §D2).
+ *
+ * Every selector is a JSONPath-lite expression (`src/core/feeds/_jsonpath.ts`).
+ *
+ * Every field is optional. When omitted the adapter falls back to a default
+ * selector chain per field (#174 / ADR-0012 §D2 defaults). For "simple"
+ * page-based APIs (dev.to, JSON Feed-shaped) the recipe can therefore omit
+ * `jsonSelectors` entirely (or use just `{}`) and rely on:
+ *
+ *   items       — `$.items[*] || $.data[*] || $.results[*] || $.posts[*] || $.entries[*] || $[*]`
+ *   title       — `$.title || $.name || $.headline`
+ *   link        — `$.url || $.link || $.permalink || $.html_url`
+ *   publishedAt — `$.publishedAt || $.published_at || $.date || $.created_at || $.pubDate`
+ *   summary     — `$.summary || $.description || $.excerpt || $.body`
+ *
+ * - `publisherId` has no fallback chain (stable id derivation falls through
+ *   to `link` URL by default; see `derive-id.ts`).
+ * - `body` / `tags` have no fallback chain (rarely needed for normalization).
+ * - `linkBase` resolves relative `link` values against an explicit base URL
+ *   (defaults to `source.url`). See field-level docstring for details (#204).
+ *
+ * Note that selectors are evaluated against each item element (already
+ * dereferenced via `items`), so paths inside this schema commonly use `$` as
+ * the per-item root (e.g. `$.title`, `$.created_at`).
+ */
+export declare const SourceJsonApiSelectorsSchema: z.ZodObject<{
+    items: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    link: z.ZodOptional<z.ZodString>;
+    publisherId: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+    publishedAt: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodString>;
+    linkBase: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SourceJsonApiSelectors = z.infer<typeof SourceJsonApiSelectorsSchema>;
+/**
+ * Facet sweep recipe extension for `kind: json-api` (ADR-0017).
+ *
+ * `facets` is an outer "data slice" axis that wraps the inner pagination
+ * loop. It exists because some APIs cap their offset/page traversal at a
+ * fixed total (e.g. AWS dirs API: `(page + 1) * size <= 10000`), making
+ * the upper ~half of the catalog unreachable via inner pagination alone.
+ * Splitting the request by a facet (year, category, …) keeps every slice
+ * comfortably under the cap and recovers full-history coverage.
+ *
+ * Two facet types are supported in Phase 1:
+ *
+ * - `range`: a numeric range `[start, end]` (inclusive) walked with `step`.
+ *   Useful for year sweeps where the API exposes a `year=YYYY` filter.
+ * - `enum`: an explicit list of values (string / number). Useful for
+ *   non-numeric or non-sequential facets (categories, regions, tags).
+ *
+ * The `template` must contain a literal `{}` placeholder which the
+ * adapter substitutes with the current facet value (e.g.
+ * `whats-new-v2#year#{}` → `whats-new-v2#year#2024`). The substituted
+ * string is injected into the URL as the value of the `param` query
+ * parameter.
+ *
+ * Multi-facet support (e.g. year × category) is explicitly deferred to a
+ * future ADR; the adapter throws when more than one facet entry is
+ * present. The schema allows a `Record<string, Facet>` purely for
+ * forward-compatibility — single entry today, additional entries later
+ * without a schema break.
+ *
+ * See ADR-0017 for the full design rationale (option A vs option D
+ * `pagination.type: facet`, lastSeenIds-as-global semantics, conditional
+ * GET disablement in facet sweep mode).
+ */
+export declare const SourceFacetRangeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"range">;
+    param: z.ZodString;
+    template: z.ZodString;
+    range: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+    step: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type SourceFacetRange = z.infer<typeof SourceFacetRangeSchema>;
+export declare const SourceFacetEnumSchema: z.ZodObject<{
+    type: z.ZodLiteral<"enum">;
+    param: z.ZodString;
+    template: z.ZodString;
+    values: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+}, z.core.$strip>;
+export type SourceFacetEnum = z.infer<typeof SourceFacetEnumSchema>;
+export declare const SourceFacetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"range">;
+    param: z.ZodString;
+    template: z.ZodString;
+    range: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+    step: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"enum">;
+    param: z.ZodString;
+    template: z.ZodString;
+    values: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+}, z.core.$strip>], "type">;
+export type SourceFacet = z.infer<typeof SourceFacetSchema>;
+/**
+ * Map of facet-name → facet-spec. In Phase 1 the adapter enforces a
+ * single entry at runtime (multi-facet is deferred to a future ADR), but
+ * the schema accepts the record shape so future multi-facet support does
+ * not require a schema break.
+ */
+export declare const SourceFacetsSchema: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"range">;
+    param: z.ZodString;
+    template: z.ZodString;
+    range: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+    step: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"enum">;
+    param: z.ZodString;
+    template: z.ZodString;
+    values: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+}, z.core.$strip>], "type">>;
+export type SourceFacets = z.infer<typeof SourceFacetsSchema>;
 export declare const SourceSchema: z.ZodObject<{
     id: z.ZodString;
     kind: z.ZodEnum<{
@@ -133,6 +309,8 @@ export declare const SourceSchema: z.ZodObject<{
         "html-js": "html-js";
         "github-releases": "github-releases";
         "npm-registry": "npm-registry";
+        "json-feed": "json-feed";
+        "json-api": "json-api";
     }>;
     url: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
@@ -172,6 +350,50 @@ export declare const SourceSchema: z.ZodObject<{
         timeout: z.ZodDefault<z.ZodNumber>;
         userAgent: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    http: z.ZodOptional<z.ZodObject<{
+        method: z.ZodDefault<z.ZodLiteral<"GET">>;
+        headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+    pagination: z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<{
+            page: "page";
+            offset: "offset";
+            cursor: "cursor";
+            "link-header": "link-header";
+            token: "token";
+            none: "none";
+        }>;
+        param: z.ZodOptional<z.ZodString>;
+        start: z.ZodOptional<z.ZodNumber>;
+        pageSize: z.ZodOptional<z.ZodNumber>;
+        pageSizeParam: z.ZodOptional<z.ZodString>;
+        nextCursorPath: z.ZodOptional<z.ZodString>;
+        totalPath: z.ZodOptional<z.ZodString>;
+        maxPages: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    jsonSelectors: z.ZodOptional<z.ZodObject<{
+        items: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        link: z.ZodOptional<z.ZodString>;
+        publisherId: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+        publishedAt: z.ZodOptional<z.ZodString>;
+        body: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodString>;
+        linkBase: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    facets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"range">;
+        param: z.ZodString;
+        template: z.ZodString;
+        range: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+        step: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"enum">;
+        param: z.ZodString;
+        template: z.ZodString;
+        values: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    }, z.core.$strip>], "type">>>;
     trustLevel: z.ZodDefault<z.ZodEnum<{
         trusted: "trusted";
         untrusted: "untrusted";

package/dist/schemas/source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/schemas/source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,gBAAgB;;;;;;EAM3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;;;;EAAyC,CAAC;AACtE,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,qGAAqG;AACrG,eAAO,MAAM,gBAAgB;;;;;EAA+C,CAAC;AAC7E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB;;;EAAmC,CAAC;AACjE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;iBAM9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;iBAQhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;iBAKhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAoBpE,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+CrB,CAAC;AACL,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC"}
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/schemas/source.ts"],"names":[],"mappings":"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"}

package/dist/schemas/source.js

@@ -5,6 +5,8 @@ export const SourceKindSchema = z.enum([
     "html-js",
     "github-releases",
     "npm-registry",
+    "json-feed",
+    "json-api",
 ]);
 /**
  * Match modes for keyword evaluation (ADR-0006).
@@ -93,6 +95,212 @@ export const SourceJsOptionsSchema = z.object({
     timeout: z.number().int().positive().default(30000),
     userAgent: z.string().optional(),
 });
+/**
+ * HTTP options for `kind: json-api` sources (ADR-0012 §D2).
+ *
+ * Phase 1 supports GET only. `headers` accepts arbitrary key/value pairs and
+ * supports `${VAR}` env-var interpolation (resolved by the adapter, never
+ * persisted to log / frontmatter — see ADR-0012 §D5c).
+ *
+ * The schema deliberately does not validate header values against env names —
+ * the adapter handles unresolved `${VAR}` placeholders by omitting the header
+ * (degraded fetch). This lets public APIs work without env wiring while
+ * authenticated APIs fail-fast with a 401/403 at runtime.
+ */
+export const SourceHttpOptionsSchema = z.object({
+    method: z.literal("GET").default("GET"),
+    headers: z.record(z.string(), z.string()).default({}),
+});
+/**
+ * Pagination configuration for `kind: json-api` sources (ADR-0012 §D2).
+ *
+ * Five wire formats are supported:
+ *
+ *   page         — `?page=K&pageSize=N` (e.g. AWS What's New, dev.to)
+ *   offset       — `?offset=K&limit=N`
+ *   cursor       — `?after=<cursorValue>` with `nextCursor` extracted via JSONPath
+ *   link-header  — `Link: <...>; rel="next"` HTTP header
+ *   token        — `?pageToken=<opaque>` opaque continuation token
+ *   none         — single request, no pagination
+ *
+ * `maxPages` is a hard cap to prevent runaway loops / DoS on misconfigured
+ * recipes. The default (20) matches a conservative bound for normal-mode
+ * fetching; `--backfill` can override via `--max-pages` to walk further.
+ *
+ * `nextCursorPath` / `totalPath` are JSONPath-lite expressions resolved against
+ * the parsed response body. `totalPath` is consulted in backfill mode to
+ * compute an upper bound on pages and short-circuit early when the total is
+ * known.
+ */
+export const SourcePaginationSchema = z.object({
+    type: z.enum(["page", "offset", "cursor", "link-header", "token", "none"]),
+    /**
+     * Query parameter name for the page / offset / token (e.g. `page`, `offset`,
+     * `after`, `pageToken`). Required for `page` / `offset` / `cursor` / `token`;
+     * ignored for `link-header` / `none`.
+     */
+    param: z.string().min(1).optional(),
+    /** Initial value (e.g. 0 for offset, 1 for page-number, undefined for cursor/token). */
+    start: z.number().int().optional(),
+    /** Items per page (e.g. 100 for AWS, 30 for dev.to). */
+    pageSize: z.number().int().positive().optional(),
+    /** Query parameter name for the page-size value. Defaults to `pageSize` when present. */
+    pageSizeParam: z.string().min(1).optional(),
+    /** JSONPath-lite to the next-cursor / next-token value in the response body. */
+    nextCursorPath: z.string().min(1).optional(),
+    /** JSONPath-lite to the total-count value in the response body (backfill-mode early-stop hint). */
+    totalPath: z.string().min(1).optional(),
+    /** Hard cap on pages traversed. Default 20 (normal mode); `--max-pages` overrides in backfill. */
+    maxPages: z.number().int().positive().default(20),
+});
+/**
+ * Selector ruleset for `kind: json-api` sources (ADR-0012 §D2).
+ *
+ * Every selector is a JSONPath-lite expression (`src/core/feeds/_jsonpath.ts`).
+ *
+ * Every field is optional. When omitted the adapter falls back to a default
+ * selector chain per field (#174 / ADR-0012 §D2 defaults). For "simple"
+ * page-based APIs (dev.to, JSON Feed-shaped) the recipe can therefore omit
+ * `jsonSelectors` entirely (or use just `{}`) and rely on:
+ *
+ *   items       — `$.items[*] || $.data[*] || $.results[*] || $.posts[*] || $.entries[*] || $[*]`
+ *   title       — `$.title || $.name || $.headline`
+ *   link        — `$.url || $.link || $.permalink || $.html_url`
+ *   publishedAt — `$.publishedAt || $.published_at || $.date || $.created_at || $.pubDate`
+ *   summary     — `$.summary || $.description || $.excerpt || $.body`
+ *
+ * - `publisherId` has no fallback chain (stable id derivation falls through
+ *   to `link` URL by default; see `derive-id.ts`).
+ * - `body` / `tags` have no fallback chain (rarely needed for normalization).
+ * - `linkBase` resolves relative `link` values against an explicit base URL
+ *   (defaults to `source.url`). See field-level docstring for details (#204).
+ *
+ * Note that selectors are evaluated against each item element (already
+ * dereferenced via `items`), so paths inside this schema commonly use `$` as
+ * the per-item root (e.g. `$.title`, `$.created_at`).
+ */
+export const SourceJsonApiSelectorsSchema = z.object({
+    items: z.string().min(1).optional(),
+    title: z.string().min(1).optional(),
+    link: z.string().min(1).optional(),
+    publisherId: z.string().min(1).optional(),
+    summary: z.string().min(1).optional(),
+    publishedAt: z.string().min(1).optional(),
+    body: z.string().min(1).optional(),
+    tags: z.string().min(1).optional(),
+    /**
+     * Base URL used to resolve relative `link` values returned by the API
+     * (#204). Many APIs (e.g. AWS What's New) return `headlineUrl` as a path
+     * like `/about-aws/whats-new/.../` instead of a full URL, which causes
+     * every item to be silently dropped at `ItemSchema` validation. When
+     * `linkBase` is set, the adapter resolves relative `link` values against
+     * it (`new URL(raw, linkBase)`); when omitted, `source.url` is used as
+     * the base, mirroring how the html adapter resolves `<a href="/...">`.
+     * Absolute links pass through untouched in either case.
+     *
+     * Must be a fully-qualified http(s) URL — invalid bases would silently
+     * mis-resolve, so we fail-fast at schema parse time.
+     */
+    linkBase: z.string().url().optional(),
+});
+/**
+ * Facet sweep recipe extension for `kind: json-api` (ADR-0017).
+ *
+ * `facets` is an outer "data slice" axis that wraps the inner pagination
+ * loop. It exists because some APIs cap their offset/page traversal at a
+ * fixed total (e.g. AWS dirs API: `(page + 1) * size <= 10000`), making
+ * the upper ~half of the catalog unreachable via inner pagination alone.
+ * Splitting the request by a facet (year, category, …) keeps every slice
+ * comfortably under the cap and recovers full-history coverage.
+ *
+ * Two facet types are supported in Phase 1:
+ *
+ * - `range`: a numeric range `[start, end]` (inclusive) walked with `step`.
+ *   Useful for year sweeps where the API exposes a `year=YYYY` filter.
+ * - `enum`: an explicit list of values (string / number). Useful for
+ *   non-numeric or non-sequential facets (categories, regions, tags).
+ *
+ * The `template` must contain a literal `{}` placeholder which the
+ * adapter substitutes with the current facet value (e.g.
+ * `whats-new-v2#year#{}` → `whats-new-v2#year#2024`). The substituted
+ * string is injected into the URL as the value of the `param` query
+ * parameter.
+ *
+ * Multi-facet support (e.g. year × category) is explicitly deferred to a
+ * future ADR; the adapter throws when more than one facet entry is
+ * present. The schema allows a `Record<string, Facet>` purely for
+ * forward-compatibility — single entry today, additional entries later
+ * without a schema break.
+ *
+ * See ADR-0017 for the full design rationale (option A vs option D
+ * `pagination.type: facet`, lastSeenIds-as-global semantics, conditional
+ * GET disablement in facet sweep mode).
+ */
+export const SourceFacetRangeSchema = z
+    .object({
+    type: z.literal("range"),
+    /** Query parameter name to inject (e.g. `tags.id`). */
+    param: z.string().min(1),
+    /**
+     * Template string with a literal `{}` placeholder for the facet value.
+     * E.g. `whats-new-v2#year#{}` → injected as `whats-new-v2#year#2024`.
+     */
+    template: z.string().min(1),
+    /** Inclusive `[start, end]` range — both endpoints are visited. */
+    range: z.tuple([z.number(), z.number()]),
+    /** Step size (default 1). Must be a positive integer. */
+    step: z.number().int().positive().default(1),
+})
+    .superRefine((value, ctx) => {
+    if (!value.template.includes("{}")) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["template"],
+            message: "template must contain '{}' placeholder",
+        });
+    }
+    if (value.range[0] > value.range[1]) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["range"],
+            message: "range start must be <= end",
+        });
+    }
+});
+export const SourceFacetEnumSchema = z
+    .object({
+    type: z.literal("enum"),
+    /** Query parameter name to inject (e.g. `category`). */
+    param: z.string().min(1),
+    /**
+     * Template string with a literal `{}` placeholder for the facet value.
+     * The adapter coerces non-string values via `String(value)` before
+     * substitution.
+     */
+    template: z.string().min(1),
+    /** Explicit list of facet values to sweep. */
+    values: z.array(z.union([z.string(), z.number()])).min(1),
+})
+    .superRefine((value, ctx) => {
+    if (!value.template.includes("{}")) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["template"],
+            message: "template must contain '{}' placeholder",
+        });
+    }
+});
+export const SourceFacetSchema = z.discriminatedUnion("type", [
+    SourceFacetRangeSchema,
+    SourceFacetEnumSchema,
+]);
+/**
+ * Map of facet-name → facet-spec. In Phase 1 the adapter enforces a
+ * single entry at runtime (multi-facet is deferred to a future ADR), but
+ * the schema accepts the record shape so future multi-facet support does
+ * not require a schema break.
+ */
+export const SourceFacetsSchema = z.record(z.string().min(1), SourceFacetSchema);
 /**
  * Validate `Source.url` per kind.
  *
@@ -137,6 +345,19 @@ export const SourceSchema = z
     // existing source YAMLs (and `kind: html` ones) parse unchanged; the
     // adapter applies defaults when the field is omitted entirely.
     js: SourceJsOptionsSchema.optional(),
+    // `http` / `pagination` / `jsonSelectors` are consulted only by the
+    // `json-api` adapter (ADR-0012). Marked optional so existing source YAMLs
+    // and other kinds parse unchanged. The `jsonSelectors` name disambiguates
+    // from the css-selector `selectors` field that html / html-js use.
+    http: SourceHttpOptionsSchema.optional(),
+    pagination: SourcePaginationSchema.optional(),
+    jsonSelectors: SourceJsonApiSelectorsSchema.optional(),
+    // Facet sweep recipe extension (ADR-0017). Independent of
+    // `pagination`: `facets` is the outer "data slice" axis, `pagination`
+    // is the inner per-request page traversal. Only consulted by the
+    // `json-api` adapter. Single-facet only in Phase 1 — multi-facet is
+    // schema-allowed for forward-compat but the adapter throws at runtime.
+    facets: SourceFacetsSchema.optional(),
     // `trustLevel` defaults to `"untrusted"` so existing source YAMLs (which
     // omit the field entirely) keep their current treatment. Per ADR-0009 M4
     // this is schema-only; policy branches that read `trustLevel` arrive in a
@@ -158,5 +379,18 @@ export const SourceSchema = z
             message: `selectors is required when kind is '${value.kind}'`,
         });
     }
+    if (value.kind === "json-api") {
+        // `jsonSelectors` is now optional — when omitted the adapter relies on
+        // its default selector chain (ADR-0012 §D2 / #174). Most "simple"
+        // page-based APIs work with just `pagination` set; complex shapes
+        // (AWS What's New, nested fields) still need explicit selectors.
+        if (value.pagination === undefined) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["pagination"],
+                message: "pagination is required when kind is 'json-api'",
+            });
+        }
+    }
 });
 //# sourceMappingURL=source.js.map

package/dist/schemas/source.js.map

@@ -1 +1 @@
-{"version":3,"file":"source.js","sourceRoot":"","sources":["../../src/schemas/source.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../../src/schemas/source.ts"],"names":[],"mappings":"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"}

package/dist/templates/agents/AGENTS.md

@@ -48,22 +48,52 @@ radar init --with-actions           # .github/workflows/watch.yaml を生成
 radar init --force                  # 既存ファイルを上書き
 
 # 監視対象の管理
-radar source add <id> --kind <rss|html|html-js|github-releases|npm-registry> --url <url> [options]
+radar source add <id> --kind <rss|html|html-js|github-releases|npm-registry|json-feed|json-api> --url <url> [options]
 radar source list
+radar source recipes                                   # バンドル recipe を一覧表示 (ADR-0012)
+radar source add <id> --recipe <name> [--keywords ... --tags ... --name ...]  # recipe ベースで 1 行追加
 radar source test <id> [--limit N] [--show-content]   # state/items を書き換えず取得 + フィルタを試す
 radar source remove <id>
 
+# JSON API recipe を pagination 付きで追加（ADR-0012）
+# `facets:` (年・カテゴリ単位の sweep) は flag では設定できず recipe のみ (ADR-0017)
+radar source add aws-whats-new --kind json-api \
+  --url "https://aws.amazon.com/api/dirs/items/search?item.directoryId=whats-new-v2&size=100&page=0" \
+  --keywords "Bedrock,Claude" \
+  --pagination-strategy page --page-size 100 --max-pages 30
+
+# 同じことを bundled recipe で 1 行で (year facet sweep 付き、全 21,834 件カバー)
+radar source add aws-watch --recipe aws-whats-new --keywords "Bedrock,Claude"
+
+# JSON Feed (1.0 / 1.1) は URL のみで動く zero-config
+radar source add example-microblog --kind json-feed \
+  --url https://example.micro.blog/feed.json \
+  --keywords "release"
+
 # 監視実行 (新着検出 → items/*.yaml に detected で書く)
 radar watch run
 
+# 過去全履歴の一括取り込み (kind: json-api / github-releases / npm-registry)
+# AWS は recipe の facets.year + per-facet maxPages=30 で 21,834 件を完全カバー (ADR-0017)
+radar watch run --source aws-whats-new --backfill
+
 # 検出済み item に対する操作
-radar research <item-id> --agent <agent>     # 調査レポートを生成 (status: detected -> researched)
+radar research <item-id> --agent <agent> [--verbose]   # 調査レポートを生成 (status: detected -> researched)。--verbose で agent stdout を直接見る (ADR-0015)
 radar research --digest <item-id> <item-id> ... [--agent <agent>]  # 複数 item を 1 digest にまとめる (ADR-0011)
+radar research --batch [--max-items N] [--filter-tags <list>] [--agent <agent>]  # detected を一括 research (ADR-0014 D3a、--max-items 既定 10)
 radar review <research-id> --agent <agent>   # 既存レポートをレビュー (status: researched -> reviewed)
 radar update <research-id> --agent <agent>   # v+1 を生成 (item status は変えない)
 radar dismiss <item-id>                       # LLM 不要、item を dismissed に
+
+# GitHub Actions workflow の後追い生成 (ADR-0014)
+radar workflow generate watch [--cron "<expr>"] [--agent <agent>] [--output <path>]
+radar workflow generate combined [--watch-cron "<expr>"] [--max-items N] [--filter-tags <list>] [--agent <agent>] [--output <path>]
 ```
 
+> **自動 research のコスト管理 (重要)**: `radar workflow generate combined` は watch → 自動 research を連鎖する workflow を生成し、`--max-items N` (既定 10) のハードキャップを YAML literal + CLI default の **二重防御**で焼き込む (ADR-0014 D3a)。`--max-items 100` のように大きい値を渡す前に必ず agent provider の billing alert を設定すること。暴走に気付いたら GitHub UI から workflow を `Disable workflow` で即停止する。詳細は `docs/user-guide.md` の「[`radar workflow generate`](https://github.com/ozzy-labs/feedradar/blob/main/docs/user-guide.md#radar-workflow-generate)」を参照。
+>
+> **進捗表示 (ADR-0015)**: `research` / `review` / `update` / `watch run --backfill` / html-js fetch / `source test` は stderr に phase markers + spinner + 副次メトリクス (`stdout` / `output` / `page x/N`) を出力する。`--verbose` で agent stdout を pass-through（デバッグ・「フリーズに見える」時の第一手）、`--quiet` または `RADAR_NO_PROGRESS=1` で完全に黙らせる。詳細は `docs/user-guide.md` の「[進捗表示 / verbose / quiet](https://github.com/ozzy-labs/feedradar/blob/main/docs/user-guide.md#進捗表示--verbose--quiet)」を参照。
+
 `<agent>` の値: `claude-code` / `codex-cli` / `gemini-cli` / `copilot`
 
 ## 利用可能な slash commands (4 agent 共通)
@@ -145,7 +175,7 @@ agent の選択は CLI が強制せず、ユーザー判断です。
 
 ## セキュリティ警告 (untrusted external content)
 
-`radar` が fetch する外部 feed (RSS / HTML / HTML (JS rendered, `kind: html-js`) / GitHub Releases / npm registry) のコンテンツは **untrusted** として扱われます ([ADR-0009](https://github.com/ozzy-labs/feedradar/blob/main/docs/adr/0009-untrusted-external-content-handling.md))。攻撃者が feed 内容に prompt injection を仕込む可能性があるため:
+`radar` が fetch する外部 feed (RSS / HTML / HTML (JS rendered, `kind: html-js`) / GitHub Releases / npm registry / JSON Feed / JSON API) のコンテンツは **untrusted** として扱われます ([ADR-0009](https://github.com/ozzy-labs/feedradar/blob/main/docs/adr/0009-untrusted-external-content-handling.md))。攻撃者が feed 内容に prompt injection を仕込む可能性があるため:
 
 - agent に渡すコンテンツは boundary marker で囲まれ、procedure 本体と分離される
 - `sources/<id>.yaml` の `trustLevel` で `"trusted" | "untrusted"` を per-source で指定可能 (既定 `"untrusted"`)