@distilled.cloud/core 1.0.0-rc.1 → 1.0.0-rc.10

package/src/protocol-http.ts

@@ -22,10 +22,12 @@ import {
   keyDictionarySymbol,
   labelSymbol,
   querySymbol,
+  stringEncodedSymbol,
   unionCasesSymbol,
   type ErrorMatcher,
   type HttpTrait,
   type KeyDictionaryEntries,
+  type UnionDiscriminator,
 } from "./trait.ts";
 
 //#region AST helpers (survive S.optional / Suspend / transforms)
@@ -167,13 +169,19 @@ export const mapKeys = (
 
   // Discriminated union whose cases the API returns merged (every case's
   // keys present, `null` for the inactive ones). Map wire names, then keep
-  // only the active case's keys. A case does NOT need every key present —
-  // arms carry optional members the wire may omit — so the active case is
-  // the one that best EXPLAINS the value: most present, non-null keys
-  // covered, minus present keys the case cannot explain (ties break by
-  // coverage, then declaration order).
+  // only the active case's keys. The case is read off the union's
+  // discriminator when it has one — cases that share a key set (every
+  // resource kind of `resource_tagging`, every page-rule action) are
+  // indistinguishable by keys alone. Without one, a case does NOT need every
+  // key present — arms carry optional members the wire may omit — so the
+  // active case is the one that best EXPLAINS the value: most present,
+  // non-null keys covered, minus present keys the case cannot explain (ties
+  // break by coverage, then declaration order).
   const unionCases = getAnn(ast, unionCasesSymbol) as
-    | ReadonlyArray<ReadonlyArray<string>>
+    | {
+        readonly cases: ReadonlyArray<ReadonlyArray<string>>;
+        readonly discriminator?: UnionDiscriminator;
+      }
     | undefined;
   if (unionCases && direction === "decode" && !Array.isArray(value)) {
     const obj = (
@@ -182,25 +190,32 @@ export const mapKeys = (
     const present = Object.keys(obj).filter(
       (k) => obj[k] !== undefined && obj[k] !== null,
     );
+    const disc = unionCases.discriminator;
+    const tag = disc ? obj[disc.key] : undefined;
+    const tagged = typeof tag === "string" ? disc!.values.indexOf(tag) : -1;
     let best:
       | { keys: ReadonlyArray<string>; score: number; matched: number }
       | undefined;
-    for (const keys of unionCases) {
-      const set = new Set(keys);
-      let matched = 0;
-      let excess = 0;
-      for (const k of present) {
-        if (set.has(k)) matched++;
-        else excess++;
-      }
-      const score = matched - excess;
-      if (
-        matched > 0 &&
-        (!best ||
-          score > best.score ||
-          (score === best.score && matched > best.matched))
-      ) {
-        best = { keys, score, matched };
+    if (tagged >= 0) {
+      best = { keys: unionCases.cases[tagged]!, score: 0, matched: 0 };
+    } else {
+      for (const keys of unionCases.cases) {
+        const set = new Set(keys);
+        let matched = 0;
+        let excess = 0;
+        for (const k of present) {
+          if (set.has(k)) matched++;
+          else excess++;
+        }
+        const score = matched - excess;
+        if (
+          matched > 0 &&
+          (!best ||
+            score > best.score ||
+            (score === best.score && matched > best.matched))
+        ) {
+          best = { keys, score, matched };
+        }
       }
     }
     if (best) {
@@ -319,6 +334,18 @@ const BODYLESS = new Set(["GET", "HEAD"]);
  * filter matching nothing — the call "succeeds" with zero results and the
  * bug is invisible to the caller.
  */
+/**
+ * Value form for a `StringEncoded()` member: the string spelling of the
+ * value, element-wise for lists. `null` stays `null` — an API that models a
+ * flag as `"true" | "false"` still means "unset" by null, not `"null"`.
+ */
+const stringEncode = (value: unknown): unknown =>
+  value === null
+    ? null
+    : Array.isArray(value)
+      ? value.map(stringEncode)
+      : String(value);
+
 const appendQuery = (
   query: URLSearchParams,
   name: string,
@@ -482,12 +509,13 @@ export const buildRequest = ({
     } else if (hasPropAnn(prop, httpBodySymbol)) {
       rawBody = mapKeys(prop.type, value, "encode", rootDict);
     } else {
-      body[nameOf(prop, bodySymbol)] = mapKeys(
-        prop.type,
-        value,
-        "encode",
-        rootDict,
-      );
+      // T.StringEncoded(): the API takes this member's value only as its
+      // string spelling (`true` → `"true"`), while the TS surface keeps the
+      // natural type. Explicit here so a JSON body carries the string too,
+      // rather than relying on the multipart encoder's own `String()`.
+      body[nameOf(prop, bodySymbol)] = hasPropAnn(prop, stringEncodedSymbol)
+        ? stringEncode(value)
+        : mapKeys(prop.type, value, "encode", rootDict);
     }
   }
 
@@ -616,9 +644,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/protocol-rest.ts

@@ -30,9 +30,10 @@ import type * as AST from "effect/SchemaAST";
 import type * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
 import type * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
 import * as API from "./api.ts";
-import { makeAnnotation } from "./trait.ts";
+import { httpSymbol, makeAnnotation, type HttpTrait } from "./trait.ts";
 import {
   buildRequest,
+  getAnn,
   getPropAnn,
   getProps,
   isOpaqueValue,
@@ -185,8 +186,18 @@ export interface RestProtocolOptions<C> {
    * `<Sdk>OpContext` annotations.
    */
   readonly credentials: Effect.Effect<C, any, any>;
-  /** API base URL from the resolved credentials. */
-  readonly baseUrl: (credentials: C) => string;
+  /**
+   * API base URL from the resolved credentials. Receives the operation's
+   * route so APIs with more than one endpoint (e.g. S2's account vs
+   * per-basin hosts, chosen by path) can route per request; single-endpoint
+   * providers ignore the argument. A THROWN error (e.g. a required scope
+   * missing from the credentials) is caught and surfaced on the calling
+   * effect's error channel rather than dying as a defect.
+   */
+  readonly baseUrl: (
+    credentials: C,
+    target: { readonly uri: string; readonly method: string },
+  ) => string;
   /** Auth (and any fixed) headers from the resolved credentials. */
   readonly headers: (credentials: C) => Record<string, string>;
   /**
@@ -257,10 +268,23 @@ export const makeRestProtocol = <C>(
   }) =>
     Effect.gen(function* () {
       const creds = yield* options.credentials as Effect.Effect<C>;
+      const http = getAnn(inputAst, httpSymbol) as HttpTrait | undefined;
+      let baseUrl: string;
+      try {
+        baseUrl = options.baseUrl(creds, {
+          uri: http?.uri ?? "",
+          method: http?.method ?? "",
+        });
+      } catch (e) {
+        // A baseUrl that refuses the route (missing scope in the
+        // credentials) fails the call with that error, typed for callers by
+        // the operation's declared error channel.
+        return yield* Effect.fail(e);
+      }
       return buildRequest({
         input: unwrapRedactedDeep(input),
         inputAst,
-        baseUrl: options.baseUrl(creds),
+        baseUrl,
         headers: options.headers(creds),
         mapMemberHeader: options.mapMemberHeader,
         unknownKeyToWire: options.unknownKeyToWire,

package/src/retry.ts

@@ -121,7 +121,7 @@ export const ServerRetryHintCapMs = Context.Service<number>(
 export const serverRetryHintCapLayer = (capMs: number) =>
   Layer.succeed(ServerRetryHintCapMs, capMs);
 
-const serverRetryHintCapMsConfig: Config.Config<number> = Config.string(
+const serverRetryHintCapMsConfig: Config.Config<number> = Config.String(
   ENV_SERVER_RETRY_HINT_CAP_MS,
 ).pipe(
   Config.map((raw) => {

package/src/schema.ts

@@ -23,7 +23,7 @@ export * from "effect/Schema";
 
 import * as S from "effect/Schema";
 
-type AnyFn = (...args: any[]) => any;
+export type AnyFn = (...args: any[]) => any;
 
 // Construction surface — collapse to `any` so generics are never instantiated.
 export const optional: AnyFn = S.optional as AnyFn;
@@ -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.

package/src/trait.ts

@@ -2,7 +2,7 @@ export const annotationMetaSymbol = Symbol.for(
   "@distilled.cloud/core/annotation-meta",
 );
 
-type Annotatable = {
+export type Annotatable = {
   annotate(annotations: any): Annotatable;
 };
 
@@ -147,6 +147,20 @@ export const httpBodySymbol = Symbol.for("@distilled.cloud/core/http-body");
  */
 export const HttpBody = () => makeAnnotation(httpBodySymbol, true);
 
+export const stringEncodedSymbol = Symbol.for(
+  "@distilled.cloud/core/http/string-encoded",
+);
+/**
+ * Marks a member the API only accepts as the STRING spelling of its value —
+ * `true` travels as `"true"`, `3` as `"3"` — while the TS surface keeps the
+ * natural type (e.g. Cloudflare's multipart `validation_enabled`, which the
+ * docs model as the enum `"true" | "false"`). The protocol stringifies body
+ * members on encode, element-wise for lists; `null` is left alone. Query and
+ * header bindings already serialize their values as strings, so the trait is
+ * documentation there.
+ */
+export const StringEncoded = () => makeAnnotation(stringEncodedSymbol, true);
+
 export const formDataFileSymbol = Symbol.for(
   "@distilled.cloud/core/form-data-file",
 );
@@ -184,15 +198,37 @@ export const KeyDictionary = (dict: KeyDictionaryEntries) =>
   makeAnnotation(keyDictionarySymbol, dict);
 
 export const unionCasesSymbol = Symbol.for("@distilled.cloud/core/union-cases");
+
+/**
+ * The literal member every case of a union fixes to its own value — what the
+ * docs call the resource `type` or the action `id`. `values[i]` is the value
+ * case `i` carries.
+ */
+export interface UnionDiscriminator {
+  readonly key: string;
+  readonly values: ReadonlyArray<string>;
+}
+
 /**
  * Marks an opaque schema standing in for a discriminated union of object
  * cases, carrying each case's TS-facing key set. For APIs that return every
  * case's keys with `null` for the inactive ones, the protocol uses these key
  * sets to pick the active case and drop the others, so consumers' `"key" in
  * value` discrimination works.
+ *
+ * Key sets alone cannot tell apart cases that share them — the 41 resource
+ * kinds of `resource_tagging`, the 34 page-rule actions — so when the union
+ * has a discriminator the protocol reads the case off it and only falls back
+ * to key-set scoring for a value whose tag is missing or unknown.
  */
-export const UnionCases = (cases: ReadonlyArray<ReadonlyArray<string>>) =>
-  makeAnnotation(unionCasesSymbol, cases);
+export const UnionCases = (
+  cases: ReadonlyArray<ReadonlyArray<string>>,
+  discriminator?: UnionDiscriminator,
+) =>
+  makeAnnotation(
+    unionCasesSymbol,
+    discriminator ? { cases, discriminator } : { cases },
+  );
 //#endregion
 
 //#region Error matcher traits