@apifuse/provider-sdk 2.1.0-beta.9 → 2.2.0-beta.2

package/dist/cli/templates/provider/skills/health-checks-and-fail-closed/SKILL.md.tpl

@@ -0,0 +1,65 @@
+---
+name: health-checks-and-fail-closed
+description: Writing health checks that can actually fail, and fail-closed guards at envelope and row level. Load before writing healthCheck blocks or error handling.
+---
+
+# Health checks and fail-closed guards
+
+## Health checks that can actually fail
+`Array.isArray(data.items)` alone can never fail. Every list operation's
+health check must be able to detect the zero-rows regression.
+
+Assertion contract (per SDK `HealthCheckCase`): THROW to fail the case
+(recorded as `down`); return `{ status: "degraded", label }` to flag without
+failing; return nothing for `ok`. There is no `"down"` return value.
+
+```ts
+assertions: ({ status, data }) => {
+  if (status !== 200) {
+    throw new Error(`<op> request failed with status ${status}`);
+  }
+  if (!Array.isArray(data.items)) {
+    throw new Error("<op> missing items array");
+  }
+  // Dense query MUST return rows; zero rows = upstream contract drift
+  if (data.items.length === 0) {
+    return { status: "degraded", label: "<op> dense query returned 0 rows" };
+  }
+}
+```
+
+- Choose health-check inputs that are guaranteed-dense (major city district,
+  a stable well-known entity id). Verify the id still exists when picking it.
+- Also assert one semantic field on the first row (e.g. `items[0].name` is a
+  non-empty string) so a mapper regression that empties fields degrades too.
+
+## Fail-closed: envelope level
+- Upstream error headers/codes → structured `ProviderError` with a stable
+  `code` (`UPSTREAM_AUTH_ERROR`, `UPSTREAM_ERROR`, `NO_DATA`, ...).
+- Non-JSON body, unexpected content type → `UPSTREAM_SCHEMA_ERROR`.
+- HTTP non-2xx → classified error; never a fake empty success envelope.
+  Fixture-based tests cannot catch swallowed errors — write an explicit test:
+  mock a non-ok response and assert the handler REJECTS.
+
+## Fail-closed: row level
+Envelope guards are not enough. The silent killer is: response is valid,
+array is non-empty, but every row normalizes to nothing.
+- If a non-empty upstream collection produces zero normalized rows, throw
+  `UPSTREAM_SCHEMA_ERROR` instead of returning `items: []`.
+- Identity fields (id, name) missing on a row → throw, don't skip the row
+  silently.
+- Regression-test both layers separately: a bad envelope AND a good envelope
+  with unmappable rows.
+
+## Error message hygiene
+`ProviderError.message` reaches the tenant verbatim. Never interpolate
+upstream free text that may contain personal data (names, phone numbers,
+addresses); allowlist known code tokens and keep raw bodies in server-side
+details/logs only.
+
+## Checklist
+- [ ] Every list op health check flags 0 rows on a dense query
+- [ ] One semantic field asserted on a real row
+- [ ] Swallowed-error test exists (non-ok mock → handler rejects)
+- [ ] Non-empty upstream → zero normalized rows throws
+- [ ] No upstream free text in customer-facing error messages

package/dist/cli/templates/provider/skills/normalization-standards/SKILL.md.tpl

@@ -0,0 +1,57 @@
+---
+name: normalization-standards
+description: Public output contract rules — field naming, timestamps, enums, units, nullability. Load before writing or editing any output schema or mapper.
+---
+
+# Normalization standards
+
+Public output is the product. Apply these to every schema + mapper pair.
+
+## Field naming
+- `snake_case`, English, semantic. `emergency_phone`, not `dutyTel3`.
+- Never expose vendor key vocabularies (`hv1`..`hv12`, `MKioskTy*`, `duty*`)
+  as public field names OR as dynamic record keys. A
+  `z.record(z.string(), ...)` keyed by vendor codes is still a vendor leak —
+  map codes to a stable public vocabulary (enum keys or an array of
+  `{ code, label, status }` objects with normalized status).
+
+## Timestamps and dates
+- Public: ISO 8601 (`2026-07-07T22:28:55+09:00`, dates `2026-07-07`,
+  clock times `HH:MM`). Include the upstream's timezone offset; Korean public
+  APIs are KST (+09:00) — verify, then encode it.
+- Vendor formats (`YYYYMMDDHHmmss`, `HHmm`, unpadded `900`) are parsed inside
+  the mapper. Unparseable → `null`, plus a test for that row shape.
+- Never emit a raw vendor timestamp string in public output, including
+  fixtures.
+
+## Enums
+- Vendor status values (codes, `Y`/`N`, Korean labels like `불가능`,
+  `정보미제공`) → declared `z.enum`. Unknown value → explicit `unknown` member
+  or fail closed; never pass raw text through.
+- Map from the OFFICIAL code table, not from guessing what live samples mean.
+  Add a regression test per enum member.
+
+## Numbers and units
+- Field name states the unit: `distance_meters`, `radius_meters`,
+  `price_krw`. Mapper proves the conversion (upstream km → `* 1000`).
+- Verify the upstream unit from spec or live-data sanity check (a "distance"
+  of `1.2` from a nearby search is km, not meters). Sibling endpoints of the
+  same vendor may differ — verify each one.
+- Value-domain constraints (`nonnegative`, `min`, `max`) must reflect the
+  upstream's REAL domain observed in live data, not what seems sensible.
+  A wrong `nonnegative()` turns real negative values into `null`/errors
+  silently.
+
+## Nullability
+- `null` means "upstream did not provide it" — never "parsing failed" and
+  never a placeholder for invented data.
+- Required-for-identity fields (ids, names) missing → throw
+  `UPSTREAM_SCHEMA_ERROR`; do not emit partial rows.
+
+## Checklist before submitting a schema/mapper change
+- [ ] No vendor key visible in any public field name or record key
+- [ ] All timestamps ISO 8601 with timezone; parsing tested for real vendor
+      shapes (padded/unpadded, string/number)
+- [ ] All status-like strings are declared enums with official-table mapping
+- [ ] Every numeric field's unit is in its name and conversion is tested
+- [ ] Constraints checked against live data, not intuition

package/dist/cli/templates/provider/skills/pagination-and-counts/SKILL.md.tpl

@@ -0,0 +1,52 @@
+---
+name: pagination-and-counts
+description: total_count semantics, client-side filtering, and paging honesty. Load before implementing any list/search operation.
+---
+
+# Pagination and counts
+
+A caller uses `total_count`, `page`, and `limit` to plan iteration. If those
+numbers don't describe what the caller can actually page through, the
+operation is lying.
+
+## The client-side filtering trap
+If the upstream has no server-side filter for one of your inputs (e.g. no
+radius param) and you filter rows after fetching:
+
+- Upstream `totalCount` counts UNFILTERED rows. Returning it as your
+  `total_count` while returning filtered rows means: caller sees
+  `total_count: 541`, gets 1 row on page 1, and pages 2..28 return rows that
+  are outside the filter or empty. This is a contract failure, not a nuance.
+
+Acceptable resolutions, in preference order:
+1. **Don't accept the input.** If the upstream can't filter by it and you
+   can't enumerate all pages, drop the input from the schema and document the
+   upstream's real semantics (e.g. "results are distance-sorted; no radius
+   cutoff").
+2. **Expose upstream semantics honestly.** Distance-sorted paging with a
+   documented "no radius filter" contract and no fake `radius` input.
+3. **Filter AND fix the metadata.** If you must filter client-side, do not
+   return the upstream total. Return only what you can prove (`returned_count`
+   plus a `has_more` you can actually compute) and document that totals are
+   unavailable.
+
+Never combine: accepted filter input + client-side filter + upstream total.
+
+## Count integrity
+- Parse failure of `totalCount` → `UPSTREAM_SCHEMA_ERROR`, not `0`.
+  A fail-open zero disguises upstream drift as an empty dataset.
+- If `total_count > 0` but the page's row array normalizes to empty on
+  page 1, throw — that combination means broken extraction, not empty data.
+
+## Page/limit echo
+- Echo the EFFECTIVE values: if you clamp `limit` to the upstream max, return
+  the clamped value, not the requested one.
+- `page`/`limit` semantics must match the upstream's paging model
+  (1-indexed vs 0-indexed) — verify with two live pages, checking the
+  returned rows actually differ.
+
+## Checklist
+- [ ] No input is filtered client-side while `total_count` comes from upstream
+- [ ] totalCount parse failure fails closed
+- [ ] Effective (clamped) limit echoed
+- [ ] Two-page live check proves paging advances

package/dist/cli/templates/provider/skills/upstream-contract-verification/SKILL.md.tpl

@@ -0,0 +1,45 @@
+---
+name: upstream-contract-verification
+description: How to establish evidence for upstream request params and response fields before coding. Load before wiring any new endpoint or mapping new fields.
+---
+
+# Upstream contract verification
+
+Most provider P0s come from guessed upstream contracts. Every param name and
+response field needs evidence BEFORE it ships.
+
+## Request parameters
+1. Start from the official spec document (data.go.kr 활용가이드, vendor API
+   docs). Copy exact names — casing and underscores matter
+   (`WGS84_LAT` ≠ `WGS84LAT`; the wrong one is often silently ignored).
+2. Confirm with ONE live call per endpoint. A param being ignored does not
+   produce an error — it produces plausible-looking wrong results, so compare:
+   - filtered vs unfiltered `totalCount` (identical → param ignored)
+   - a dense-area query returning 0 rows (→ param name/format wrong)
+3. Do NOT copy param names from a sibling endpoint or sibling API of the same
+   vendor without re-verifying. Same vendor ≠ same contract; endpoints drift.
+4. If a param only works together with another param (district requires
+   province), encode that dependency in the input schema with a clear error.
+   Test it: dependent-param-alone must be rejected, not silently national.
+
+## Response fields
+- Map exactly the field names present in your recorded live fixtures.
+- No speculative fallback chains (`row.distance ?? row.dist ?? row.Distance`).
+  If two shapes genuinely exist, you need a recorded fixture proving EACH
+  branch plus a row-level test per branch; otherwise map one name only.
+- Field presence varies by endpoint within the same vendor. Detail endpoints
+  often return more/differently-named fields than list endpoints — record
+  fixtures per endpoint, not per vendor.
+
+## When results look wrong
+- Same response body across different request payloads → the upstream is
+  ignoring your variation; stop tuning fields and re-check param names/auth.
+- Empty result for a query that must have data (city-center radius search,
+  major-district listing) → treat as a request bug. Never record it as a
+  fixture and never ship it.
+
+## Deliverables per endpoint
+- [ ] Spec reference (URL or doc name + section) noted in the PR/commit
+- [ ] One recorded live fixture proving request params take effect
+- [ ] Negative evidence checked: filtered count differs from unfiltered
+- [ ] Param dependencies enforced in the input schema with tests

package/dist/cli/templates/provider/skills/upstream-notes/README.md.tpl

@@ -0,0 +1,13 @@
+# Upstream notes
+
+Per-vendor / per-API-family pitfalls proven by live evidence. These are the
+highest-value files in this workspace: general principles are knowable, but
+"this API silently ignores param X" is only discoverable by getting burned.
+
+- Read EVERY file here before your first upstream call.
+- When you discover a new upstream quirk (silently ignored param, unit
+  surprise, undocumented value domain, error-shape oddity), ADD it here in
+  the same format — evidence line included. Reviewers treat contributed
+  upstream notes as part of submission quality.
+
+Format per entry: **Symptom → Cause → Rule → Evidence**.

package/dist/cli/templates/provider/start.ts.tpl

@@ -0,0 +1,5 @@
+import { serve } from "@apifuse/provider-sdk";
+
+import provider from "./index";
+
+await serve(provider, { port: Number(process.env.APIFUSE__RUNTIME__PORT) || 3000 });

package/dist/cli/templates/provider/upstream/README.md.tpl

@@ -0,0 +1,3 @@
+# Upstream
+
+Put upstream HTTP clients, auth ceremony helpers, request builders, and protocol-specific types here once the provider talks to the real upstream service.

package/dist/contract.js

@@ -122,6 +122,7 @@ function extractHealthCheck(value) {
         return undefined;
     return compactObject({
         interval: value.interval,
+        schedule: toJsonValue(value.schedule),
         timeoutMs: value.timeoutMs,
         degradedThresholdMs: value.degradedThresholdMs,
         requiresConnection: value.requiresConnection,

package/dist/define.d.ts

@@ -1,4 +1,4 @@
-import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, InferSchemaOutput, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderDefinition, ProviderHealthMonitorConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderReviewed, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, SchemaLike, SmsOtpMatcherDefinition, StealthPlatform } from "./types";
+import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderDefinition, ProviderHealthMonitorConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderReviewed, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, SchemaLike, SmsOtpMatcherDefinition, StealthPlatform } from "./types";
 type ProviderImplementationSourceAccess = "official_api" | "private_api" | "browser_flow" | "hybrid";
 type ProviderImplementationCredentialStrategy = "apifuse_managed" | "workspace_secret" | "user_oauth" | "user_session" | "none";
 interface ProviderImplementationProfile {
@@ -80,6 +80,8 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
     };
     operations: OperationMapConfig<TOperations>;
     healthMonitor?: ProviderHealthMonitorConfig;
+    /** New name for `healthMonitor` (transitional alias); declaring both is a ValidationError. */
+    healthProbe?: ProviderHealthMonitorConfig;
     healthJourneys?: readonly HealthJourneyDefinition[];
 }
 /** Define one provider operation with schema-driven handler inference. */
@@ -88,7 +90,10 @@ export declare function defineOperation<TInput extends SchemaLike, TOutput exten
 export declare function defineStreamOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(operation: StreamOperationConfig<TInput, TOutput>): OperationDefinition<TInput, TOutput>;
 export declare function every(interval: string, options?: {
     jitter?: string;
+    randomize?: HealthScheduleRandomization;
 }): HealthJourneySchedule;
+export declare function centered(maxOffset: string): HealthScheduleRandomization;
+export declare function delayed(maxDelay: string): HealthScheduleRandomization;
 export declare function defineSmsOtpMatcher(config: Omit<SmsOtpMatcherDefinition, "extractOtp">): SmsOtpMatcherDefinition;
 export declare function defineHealthJourney(config: HealthJourneyDefinition): HealthJourneyDefinition;
 export declare function defineProvider<TOperations extends Record<string, ProviderOperation>, TConfig extends ProviderConfig<TOperations>>(config: TConfig & AuthStartNoInputGuard<TConfig>): ProviderDefinition & {