@distilled.cloud/core 1.0.0-rc.3 → 1.0.0-rc.5

package/src/codegen/openapi.ts

@@ -7,20 +7,26 @@
  * `generateService` compiler. Conversion fidelity follows distilled v0's
  * `generate-openapi.ts` feature matrix:
  *
- *   • one operation per (path × get/post/put/patch/delete), deprecated
- *     skipped by default; op shape name = PascalCase(operationId)
+ *   • one operation per (path × get/post/put/patch/delete — plus head/options
+ *     when a provider opts in via `extraHttpMethods`), deprecated skipped by
+ *     default; op shape name = PascalCase(operationId)
  *   • input `<Op>Request`: path params → `smithy.api#httpLabel` (+required),
- *     query params → `smithy.api#httpQuery`, header/cookie params dropped,
- *     body properties flattened alongside (labels win, then query, then body);
+ *     query params → `smithy.api#httpQuery`, header params →
+ *     `smithy.api#httpHeader` when `headerParams` is on (dropped otherwise,
+ *     as cookie params always are),
+ *     body properties flattened alongside
+ *     (labels win, then query, then headers, then body);
  *     non-object bodies become a sole `body` member with `smithy.api#httpPayload`
  *   • `$ref`s become NAMED shapes (`components/schemas/X` → `<ns>#X`), reused
  *     across operations; anonymous nested objects synthesize names from the
  *     parent + member path
- *   • responses: 200 → 201 → 204 precedence, `application/json` only; object
+ *   • responses: 200 → 201 → 204 precedence (`successStatuses` overrides),
+ *     `application/json` only; object
  *     results become `<Op>Response` structures (a sole `$ref` reuses the named
  *     shape); bare array/scalar results wrap in a structure whose single
  *     member carries `com.distilled.openapi#rawResponse` (the SdkSpec maps it
- *     to a root pipe); no schema → `smithy.api#Unit`
+ *     to a root pipe); no schema → `smithy.api#Unit`; `head` is always
+ *     `smithy.api#Unit`, whatever content the spec declares
  *   • nullability (3.0 `nullable`, 3.1 `type: [..., "null"]`, 2.0
  *     `x-nullable`, `oneOf`/`anyOf` null branches) → member-level
  *     `com.distilled.openapi#nullable` trait
@@ -122,6 +128,37 @@ export interface OpenApiConvertOptions {
   readonly defaultErrorStatuses?: Iterable<string>;
   /** Skip operations marked `deprecated: true`. Default true. */
   readonly skipDeprecated?: boolean;
+  /**
+   * HTTP methods to convert IN ADDITION to get/post/put/patch/delete —
+   * currently `"head"` and `"options"`. Opt-in, so a provider that models
+   * them (Vercel probes cache artifacts and sandbox files with HEAD) gets
+   * them without every other provider silently gaining operations.
+   *
+   * `head` operations always output `smithy.api#Unit` — see the output-shape
+   * comment in {@link convertOpenApiToSmithy} for why a declared response
+   * body on a HEAD can never arrive.
+   */
+  readonly extraHttpMethods?: readonly ("head" | "options")[];
+  /**
+   * Emit `in: header` parameters as `smithy.api#httpHeader` members instead
+   * of dropping them. Opt-in for the same reason as
+   * {@link extraHttpMethods}: turning it on adds input members to every
+   * operation whose spec declares a header parameter, and most providers
+   * declare ones the protocol already sends itself (Accept, Authorization,
+   * an API-version pin). Providers whose headers are real per-call inputs
+   * — Vercel's `x-Artifact-*` remote-cache metadata, `x-Vercel-Digest` —
+   * ask for them.
+   */
+  readonly headerParams?: boolean;
+  /**
+   * Response statuses to read the operation's output shape from, most
+   * preferred first. Default `["200", "201", "204"]`. Extend it for an API
+   * that answers asynchronous work with a body under another status — Vercel
+   * returns `202 Accepted` with a payload from nine endpoints (artifact
+   * upload, account deletion, VCR blob/manifest writes), which would
+   * otherwise generate as a `void` output.
+   */
+  readonly successStatuses?: readonly string[];
   /**
    * Azure-style fixed `api-version`: drops `api-version` query params and
    * stamps {@link API_VERSION_TRAIT} on every operation.
@@ -177,6 +214,24 @@ const memberIdent = (name: string): string => {
   return out || "_";
 };
 
+/**
+ * Header name → member identifier (`x-Artifact-Tag` → `xArtifactTag`). The
+ * wire name is carried by the `smithy.api#httpHeader` trait, so the member
+ * can read like the rest of the input rather than like a header.
+ */
+const headerMemberName = (name: string): string => {
+  const parts = name.split(/[^A-Za-z0-9]+/).filter(Boolean);
+  if (parts.length === 0) return "_";
+  const out = parts
+    .map((p, i) =>
+      i === 0
+        ? p.charAt(0).toLowerCase() + p.slice(1)
+        : p.charAt(0).toUpperCase() + p.slice(1),
+    )
+    .join("");
+  return /^[0-9]/.test(out) ? `_${out}` : out;
+};
+
 const enumMemberName = (value: string): string => {
   let out = value
     .toUpperCase()
@@ -937,7 +992,11 @@ const collectParams = (ctx: Ctx, pathItem: any, op: any): Param[] => {
     byKey.set(`${p.in}${p.name}`, p);
   }
   return [...byKey.values()].filter(
-    (p) => p.in === "path" || p.in === "query" || p.in === "body",
+    (p) =>
+      p.in === "path" ||
+      p.in === "query" ||
+      p.in === "body" ||
+      p.in === "header",
   );
 };
 
@@ -1001,12 +1060,13 @@ const opDoc = (op: any): string | undefined => {
 // Responses
 // ============================================================================
 
-/** 200 → 201 → 204 precedence; response-level `$ref` resolved; JSON only. */
+/** First declared status in `order` wins; response-level `$ref` resolved; JSON only. */
 const successSchema = (
   ctx: Ctx,
   responses: any,
+  order: readonly string[],
 ): { schema: any | undefined } => {
-  for (const code of ["200", "201", "204"]) {
+  for (const code of order) {
     const raw = responses?.[code];
     if (!raw) continue;
     const resp = raw.$ref ? resolvePointer(ctx.spec, raw.$ref) : raw;
@@ -1099,6 +1159,14 @@ const detectPagination = (
 
 const HTTP_METHODS = ["get", "post", "put", "patch", "delete"] as const;
 
+/**
+ * Methods a spec may declare beyond {@link HTTP_METHODS}, opt-in via
+ * {@link OpenApiConvertOptions.extraHttpMethods} — a provider that models
+ * `head` (Vercel's cache-artifact and file existence probes) asks for it
+ * rather than every provider silently gaining operations on regeneration.
+ */
+const OPTIONAL_HTTP_METHODS = ["head", "options"] as const;
+
 const DEFAULT_STATUS_TO_ERROR_CLASS: Readonly<Record<string, string>> = {
   "400": "BadRequest",
   "403": "Forbidden",
@@ -1109,6 +1177,8 @@ const DEFAULT_STATUS_TO_ERROR_CLASS: Readonly<Record<string, string>> = {
 
 const DEFAULT_ERROR_STATUSES = ["401", "429", "500", "503"];
 
+const DEFAULT_SUCCESS_STATUSES = ["200", "201", "204"];
+
 export const convertOpenApiToSmithy = (
   spec: unknown,
   options: OpenApiConvertOptions,
@@ -1131,6 +1201,13 @@ export const convertOpenApiToSmithy = (
     options.defaultErrorStatuses ?? DEFAULT_ERROR_STATUSES,
   );
   const skipDeprecated = options.skipDeprecated ?? true;
+  const successStatuses = options.successStatuses ?? DEFAULT_SUCCESS_STATUSES;
+  const httpMethods = [
+    ...HTTP_METHODS,
+    ...OPTIONAL_HTTP_METHODS.filter((m) =>
+      options.extraHttpMethods?.includes(m),
+    ),
+  ];
 
   // Error class names and the service name are reserved up front so schema
   // components can never steal them.
@@ -1145,7 +1222,7 @@ export const convertOpenApiToSmithy = (
 
   for (const [rawPath, pathItem] of Object.entries(doc.paths ?? {})) {
     if (!pathItem || typeof pathItem !== "object") continue;
-    for (const method of HTTP_METHODS) {
+    for (const method of httpMethods) {
       const op = (pathItem as any)[method];
       if (!op || typeof op !== "object") continue;
       if (skipDeprecated && op.deprecated === true) continue;
@@ -1212,6 +1289,32 @@ export const convertOpenApiToSmithy = (
         });
       }
 
+      // ---- Header params (opt-in) ----
+      if (options.headerParams) {
+        for (const p of params) {
+          if (p.in !== "header") continue;
+          const conv = convertSchema(
+            ctx,
+            p.schema,
+            `${opName}Request${pascal(p.name)}`,
+            0,
+            "in",
+          );
+          addMember(headerMemberName(p.name), {
+            target: conv.target,
+            traits: {
+              // The wire name rides on the trait, so the member is free to be
+              // a normal identifier.
+              "smithy.api#httpHeader": p.name,
+              ...(p.required ? { "smithy.api#required": {} } : {}),
+              ...(p.description
+                ? { "smithy.api#documentation": p.description }
+                : {}),
+            },
+          });
+        }
+      }
+
       // ---- Request body (json > form-urlencoded > multipart) ----
       let contentType: "form-urlencoded" | "multipart" | undefined;
       let bodySchema: any;
@@ -1289,7 +1392,19 @@ export const convertOpenApiToSmithy = (
           : PRELUDE.Unit;
 
       // ---- Output shape ----
-      const { schema: respSchema } = successSchema(ctx, op.responses);
+      // A HEAD response carries no content, and not merely by convention:
+      // HTTP/1.1 framing terminates it at the end of the header section
+      // "regardless of the header fields present in the message" (RFC 9112
+      // §6.3), so a declared `Content-Length` describes what a GET *would*
+      // return and no body can reach the client. Specs declare one anyway —
+      // Vercel mirrors the GET's schema onto two of its HEAD probes and
+      // gives the other two a bare `{"nullable": true}` — and honouring it
+      // generates an output struct with required members that then fails to
+      // decode against the empty body on every successful call.
+      const { schema: respSchema } =
+        method === "head"
+          ? { schema: undefined }
+          : successSchema(ctx, op.responses, successStatuses);
       let outputTarget: string = PRELUDE.Unit;
       if (respSchema !== undefined) {
         const flat = flattenObject(ctx, respSchema);

package/src/errors.ts

@@ -33,7 +33,7 @@ export const DurationSchema = Schema.declare<Duration.Duration>(
 /**
  * Unauthorized - Authentication failure (401).
  */
-export class Unauthorized extends Schema.TaggedErrorClass<Unauthorized>()(
+export class Unauthorized extends Schema.TaggedError<Unauthorized>()(
   "Unauthorized",
   { message: Schema.String },
 ).pipe(Category.withAuthError) {}
@@ -41,37 +41,35 @@ export class Unauthorized extends Schema.TaggedErrorClass<Unauthorized>()(
 /**
  * Forbidden - Access denied (403).
  */
-export class Forbidden extends Schema.TaggedErrorClass<Forbidden>()(
-  "Forbidden",
-  { message: Schema.String },
-).pipe(Category.withAuthError) {}
+export class Forbidden extends Schema.TaggedError<Forbidden>()("Forbidden", {
+  message: Schema.String,
+}).pipe(Category.withAuthError) {}
 
 /**
  * NotFound - Resource not found (404).
  */
-export class NotFound extends Schema.TaggedErrorClass<NotFound>()("NotFound", {
+export class NotFound extends Schema.TaggedError<NotFound>()("NotFound", {
   message: Schema.String,
 }).pipe(Category.withNotFoundError) {}
 
 /**
  * BadRequest - Invalid request (400).
  */
-export class BadRequest extends Schema.TaggedErrorClass<BadRequest>()(
-  "BadRequest",
-  { message: Schema.String },
-).pipe(Category.withBadRequestError) {}
+export class BadRequest extends Schema.TaggedError<BadRequest>()("BadRequest", {
+  message: Schema.String,
+}).pipe(Category.withBadRequestError) {}
 
 /**
  * Conflict - Resource conflict (409).
  */
-export class Conflict extends Schema.TaggedErrorClass<Conflict>()("Conflict", {
+export class Conflict extends Schema.TaggedError<Conflict>()("Conflict", {
   message: Schema.String,
 }).pipe(Category.withConflictError) {}
 
 /**
  * UnprocessableEntity - Validation error (422).
  */
-export class UnprocessableEntity extends Schema.TaggedErrorClass<UnprocessableEntity>()(
+export class UnprocessableEntity extends Schema.TaggedError<UnprocessableEntity>()(
   "UnprocessableEntity",
   { message: Schema.String },
 ).pipe(Category.withBadRequestError) {}
@@ -79,7 +77,7 @@ export class UnprocessableEntity extends Schema.TaggedErrorClass<UnprocessableEn
 /**
  * TooManyRequests - Rate limited (429).
  */
-export class TooManyRequests extends Schema.TaggedErrorClass<TooManyRequests>()(
+export class TooManyRequests extends Schema.TaggedError<TooManyRequests>()(
   "TooManyRequests",
   {
     message: Schema.String,
@@ -93,7 +91,7 @@ export class TooManyRequests extends Schema.TaggedErrorClass<TooManyRequests>()(
 /**
  * Locked - Resource locked (423).
  */
-export class Locked extends Schema.TaggedErrorClass<Locked>()("Locked", {
+export class Locked extends Schema.TaggedError<Locked>()("Locked", {
   message: Schema.String,
   retryAfter: Schema.optional(DurationSchema),
 }).pipe(Category.withLockedError, Category.withRetryable()) {}
@@ -106,7 +104,7 @@ export class Locked extends Schema.TaggedErrorClass<Locked>()("Locked", {
  * 200 envelope carrying `{ code: 10002, message: "An unknown error has
  * occurred" }` for transient backend failures on some endpoints).
  */
-export class InternalServerError extends Schema.TaggedErrorClass<InternalServerError>()(
+export class InternalServerError extends Schema.TaggedError<InternalServerError>()(
   "InternalServerError",
   {
     message: Schema.String,
@@ -118,18 +116,15 @@ export class InternalServerError extends Schema.TaggedErrorClass<InternalServerE
 /**
  * BadGateway - Bad gateway (502).
  */
-export class BadGateway extends Schema.TaggedErrorClass<BadGateway>()(
-  "BadGateway",
-  {
-    message: Schema.String,
-    retryAfter: Schema.optional(DurationSchema),
-  },
-).pipe(Category.withServerError, Category.withRetryable()) {}
+export class BadGateway extends Schema.TaggedError<BadGateway>()("BadGateway", {
+  message: Schema.String,
+  retryAfter: Schema.optional(DurationSchema),
+}).pipe(Category.withServerError, Category.withRetryable()) {}
 
 /**
  * ServiceUnavailable - Service unavailable (503).
  */
-export class ServiceUnavailable extends Schema.TaggedErrorClass<ServiceUnavailable>()(
+export class ServiceUnavailable extends Schema.TaggedError<ServiceUnavailable>()(
   "ServiceUnavailable",
   {
     message: Schema.String,
@@ -140,7 +135,7 @@ export class ServiceUnavailable extends Schema.TaggedErrorClass<ServiceUnavailab
 /**
  * GatewayTimeout - Gateway timeout (504).
  */
-export class GatewayTimeout extends Schema.TaggedErrorClass<GatewayTimeout>()(
+export class GatewayTimeout extends Schema.TaggedError<GatewayTimeout>()(
   "GatewayTimeout",
   {
     message: Schema.String,
@@ -151,7 +146,7 @@ export class GatewayTimeout extends Schema.TaggedErrorClass<GatewayTimeout>()(
 /**
  * Configuration error - missing or invalid configuration.
  */
-export class ConfigError extends Schema.TaggedErrorClass<ConfigError>()(
+export class ConfigError extends Schema.TaggedError<ConfigError>()(
   "ConfigError",
   { message: Schema.String },
 ).pipe(Category.withConfigurationError) {}

package/src/pagination.ts

@@ -5,6 +5,8 @@
  * - Page-based: page/per_page with a page number that advances
  * - Cursor-based: cursor/limit with an opaque next-cursor string
  * - Token-based (AWS style): NextToken/MaxResults continuation tokens
+ * - Relay (GraphQL connections): after/first with a `pageInfo` block whose
+ *   `hasNextPage` — not the cursor — marks the end
  * - Single: one-shot list endpoints that still expose the paginated surface
  *
  * Each SDK stores a {@link PaginatedTrait} on its operations (sourced from the
@@ -31,6 +33,33 @@ export const getPath = (obj: unknown, path: string): unknown => {
   return current;
 };
 
+/**
+ * Collect the items a dot-separated path selects, flattening arrays as it
+ * goes. Unlike {@link getPath} (which walks a single value and is used for
+ * cursors/tokens), every segment here fans out over whatever the previous one
+ * produced, so a path may cross a list:
+ *
+ * - `"items"` on `{ items: [a, b] }` → `[a, b]` (the common flat case)
+ * - `"edges.node"` on a Relay connection → every edge's `node`
+ *
+ * `null`/`undefined` links are dropped rather than propagated, so a partially
+ * null page yields the items it does have instead of nothing.
+ */
+export const getItems = (obj: unknown, path: string): readonly unknown[] => {
+  let current: unknown[] = [obj];
+  for (const part of path.split(".")) {
+    const next: unknown[] = [];
+    for (const value of current) {
+      if (value == null || typeof value !== "object") continue;
+      const child = (value as Record<string, unknown>)[part];
+      if (Array.isArray(child)) next.push(...child);
+      else if (child != null) next.push(child);
+    }
+    current = next;
+  }
+  return current;
+};
+
 // ============================================================================
 // Pagination Trait
 // ============================================================================
@@ -38,15 +67,26 @@ export const getPath = (obj: unknown, path: string): unknown => {
 /** Pagination trait describing how to navigate between pages. */
 export interface PaginatedTrait {
   /** Pagination strategy */
-  readonly mode?: "token" | "page" | "cursor" | "single";
+  readonly mode?: "token" | "page" | "cursor" | "relay" | "single";
   /** The name of the input member containing the page/cursor token */
   readonly inputToken?: string;
   /** The path to the output member containing the next page/cursor token */
   readonly outputToken?: string;
-  /** The path to the output member containing the paginated items */
+  /**
+   * The path to the output member containing the paginated items. Segments
+   * may cross arrays — `"edges.node"` walks every edge and collects its
+   * `node` (see {@link getItems}).
+   */
   readonly items?: string;
   /** The name of the input member that limits page size */
   readonly pageSize?: string;
+  /**
+   * Relay extension: the path to the boolean that says whether another page
+   * exists (`"pageInfo.hasNextPage"`). Relay connections keep returning the
+   * last page's `endCursor` after the end, so the cursor alone can't
+   * terminate traversal — see {@link paginateRelay}.
+   */
+  readonly hasNextPage?: string;
 }
 
 export type PaginationStrategy = <
@@ -261,6 +301,82 @@ export const paginateToken = <
   );
 };
 
+// ============================================================================
+// Relay Pagination (GraphQL connections)
+// ============================================================================
+
+/**
+ * Stream of pages over a Relay connection — pass `pageInfo.endCursor` back as
+ * `after` for as long as `pageInfo.hasNextPage` is true.
+ *
+ * Relay is cursor pagination with one twist that breaks
+ * {@link paginateCursor}: the terminal page still carries an `endCursor` (it
+ * points at the last edge, not at "nothing left"). Only `hasNextPage`
+ * distinguishes "more to fetch" from "that was everything", so this strategy
+ * reads the boolean and treats the cursor as a pure position marker. A
+ * connection that omits `pageInfo` entirely (or returns an empty page) also
+ * terminates, so a malformed response can't spin forever.
+ */
+export const paginateRelay = <
+  Input extends Record<string, unknown>,
+  Output,
+  E,
+  R,
+>(
+  operation: (input: Input) => Effect.Effect<Output, E, R>,
+  input: Input,
+  pagination: PaginatedTrait,
+): Stream.Stream<Output, E, R> => {
+  const inputToken = pagination.inputToken;
+  const outputToken = pagination.outputToken;
+  if (!inputToken || !outputToken) {
+    return missingPaginationConfig(
+      "Relay pagination requires inputToken and outputToken",
+    );
+  }
+  // `pageInfo.endCursor` → `pageInfo.hasNextPage` when the trait doesn't say.
+  const hasNextPath =
+    pagination.hasNextPage ??
+    `${outputToken.split(".").slice(0, -1).concat("hasNextPage").join(".")}`;
+
+  type State = { cursor: string | undefined; done: boolean };
+  const startCursor =
+    typeof input[inputToken] === "string"
+      ? (input[inputToken] as string)
+      : undefined;
+
+  return Stream.unfold({ cursor: startCursor, done: false } as State, (state) =>
+    Effect.gen(function* () {
+      if (state.done) return undefined;
+
+      const requestPayload = {
+        ...input,
+        ...(state.cursor ? { [inputToken]: state.cursor } : {}),
+      } as Input;
+
+      const response = yield* operation(requestPayload);
+
+      const nextCursor = getPath(response, outputToken) as
+        | string
+        | null
+        | undefined;
+      const hasNext = getPath(response, hasNextPath) === true;
+      // An empty page means the connection is exhausted regardless of what
+      // `hasNextPage` claims — re-requesting the same cursor would loop.
+      const emptyPage =
+        pagination.items !== undefined &&
+        getItems(response, pagination.items).length === 0;
+
+      const nextState: State = {
+        cursor: nextCursor ?? undefined,
+        done: !hasNext || isTerminalToken(nextCursor) || emptyPage,
+      };
+
+      return [response, nextState] as const;
+    }),
+  );
+};
+
 /**
  * Shared default pagination dispatcher for SDKs that use generic
  * token/cursor/page traversal.
@@ -277,6 +393,8 @@ export const paginateWithDefaults: PaginationStrategy = (
       return paginatePageNumber(operation, input, pagination);
     case "cursor":
       return paginateCursor(operation, input, pagination);
+    case "relay":
+      return paginateRelay(operation, input, pagination);
     case "single":
       return paginateSingle(operation, input, pagination);
     case "token":
@@ -293,7 +411,8 @@ export const paginateWithDefaults: PaginationStrategy = (
  * Extracts individual items from a page stream.
  *
  * @param pages - A stream of page responses
- * @param itemsPath - Dot-separated path to the items array in the page
+ * @param itemsPath - Dot-separated path to the items in the page; segments may
+ *   cross arrays (see {@link getItems})
  * @returns A Stream of individual items
  */
 export const extractItems = <Output, Item, E, R>(
@@ -301,8 +420,7 @@ export const extractItems = <Output, Item, E, R>(
   itemsPath: string,
 ): Stream.Stream<Item, E, R> =>
   pages.pipe(
-    Stream.flatMap((page) => {
-      const items = getPath(page, itemsPath) as readonly Item[] | undefined;
-      return Stream.fromIterable(items ?? []);
-    }),
+    Stream.flatMap((page) =>
+      Stream.fromIterable(getItems(page, itemsPath) as readonly Item[]),
+    ),
   );

package/src/protocol-http.ts

@@ -616,9 +616,17 @@ export const buildRequest = ({
       request = request.pipe(HttpClientRequest.bodyJsonUnsafe(rawBody));
     }
   } else if (
-    !BODYLESS.has(http.method) &&
-    (Object.keys(body).length > 0 ||
-      (hasBodyMembers && http.method !== "DELETE"))
+    // A GET/HEAD sends a body only when body members actually carry values.
+    // Some APIs really do document GET-with-body: MongoDB Atlas's
+    // `…/lineItems:search` declares a `requestBody` on `get`, and AWS EFS's
+    // DescribeAccountPreferences takes `{ MaxResults, NextToken }` on a GET.
+    // Suppressing it outright dropped those members silently — the request
+    // succeeded, unfiltered, with nothing on the wire to show why.
+    //
+    // The `{}`-when-empty rule below stays limited to methods that expect a
+    // body, so a bodyless method with nothing set still sends nothing.
+    Object.keys(body).length > 0 ||
+    (hasBodyMembers && !BODYLESS.has(http.method) && http.method !== "DELETE")
   ) {
     // Send `{}` rather than no body when the schema declares body members —
     // some endpoints reject a missing JSON body outright.

package/src/schema.ts

@@ -48,6 +48,6 @@ export const Null: any = S.Null;
 export const Void: any = S.Void;
 export const Any: any = S.Any;
 
-// NOTE: `Schema` / `Codec` (types) and `TaggedErrorClass` are intentionally NOT
+// NOTE: `Schema` / `Codec` (types) and `TaggedError` are intentionally NOT
 // overridden — they flow through `export *` with real types so cast targets and
 // typed error classes stay precise.