@detent/sdk 0.1.0

package/src/types/discriminated-union.ts

@@ -0,0 +1,101 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v4-mini";
+import { startCountingDefaultToZeroValue } from "./default-to-zero-value.js";
+import { startCountingUnrecognized } from "./unrecognized.js";
+
+const UNKNOWN = Symbol("UNKNOWN");
+
+export type Unknown<Discriminator extends string, UnknownValue = "UNKNOWN"> =
+  & {
+    [K in Discriminator]: UnknownValue;
+  }
+  & {
+    raw: unknown;
+    isUnknown: true;
+  };
+
+export function isUnknown<Discriminator extends string>(
+  value: unknown,
+): value is Unknown<Discriminator> {
+  return typeof value === "object" && value !== null && UNKNOWN in value;
+}
+
+/**
+ * Forward-compatible discriminated union parser.
+ *
+ * If the input does not match one of the predefined options, it will be
+ * captured and available as `{ raw: <original input>, [discriminator]: "UNKNOWN", isUnknown: true }`.
+ *
+ * @param inputPropertyName - The discriminator property name in the input payload
+ * @param options - Map of discriminator values to their corresponding schemas
+ * @param opts - Optional configuration object
+ * @param opts.unknownValue - The value to use for the discriminator when the input is unknown (default: "UNKNOWN")
+ * @param opts.outputPropertyName - Output property name if the sanitized (camelCase) property name differs from inputPropertyName
+ */
+export function discriminatedUnion<
+  InputDiscriminator extends string,
+  TOptions extends Readonly<Record<string, z.ZodMiniType>>,
+  UnknownValue extends string = "UNKNOWN",
+  OutputDiscriminator extends string = InputDiscriminator,
+>(
+  inputPropertyName: InputDiscriminator,
+  options: TOptions,
+  opts: {
+    unknownValue?: UnknownValue;
+    outputPropertyName?: OutputDiscriminator;
+  } = {},
+): z.ZodMiniType<
+  | z.output<TOptions[keyof TOptions]>
+  | Unknown<OutputDiscriminator, UnknownValue>,
+  unknown
+> {
+  const { unknownValue = "UNKNOWN" as UnknownValue, outputPropertyName } = opts;
+  return z.pipe(
+    z.unknown(),
+    z.transform((input) => {
+      const fallback = Object.defineProperties(
+        {
+          raw: input,
+          [outputPropertyName ?? inputPropertyName]: unknownValue,
+          isUnknown: true as const,
+        },
+        { [UNKNOWN]: { value: true, enumerable: false, configurable: false } },
+      );
+
+      const isObject = typeof input === "object" && input !== null;
+      if (!isObject) return fallback;
+
+      const discriminator = input[inputPropertyName as keyof typeof input];
+      if (typeof discriminator !== "string") return fallback;
+      if (!(discriminator in options)) return fallback;
+
+      const schema = options[discriminator];
+      if (!schema) return fallback;
+
+      // Start counters before parsing to track nested unrecognized/zeroDefault values
+      const unrecognizedCtr = startCountingUnrecognized();
+      const zeroDefaultCtr = startCountingDefaultToZeroValue();
+
+      const result = z.safeParse(schema, input);
+      if (!result.success) {
+        // Parse failed - don't propagate any counts from the failed attempt
+        unrecognizedCtr.end(0);
+        zeroDefaultCtr.end(0);
+        return fallback;
+      }
+
+      // Parse succeeded - propagate the actual counts
+      unrecognizedCtr.end();
+      zeroDefaultCtr.end();
+
+      if (outputPropertyName) {
+        (result.data as any)[outputPropertyName] = discriminator;
+      }
+
+      return result.data;
+    }),
+  ) as any;
+}

package/src/types/enums.ts

@@ -0,0 +1,45 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v4-mini";
+import { Unrecognized, unrecognized } from "./unrecognized.js";
+
+export type ClosedEnum<T extends Readonly<Record<string, string | number>>> =
+  T[keyof T];
+export type OpenEnum<T extends Readonly<Record<string, string | number>>> =
+  | T[keyof T]
+  | Unrecognized<T[keyof T] extends number ? number : string>;
+
+export function inboundSchema<T extends Record<string, string>>(
+  enumObj: T,
+): z.ZodMiniType<OpenEnum<T>, unknown> {
+  const options = Object.values(enumObj);
+  return z.union([
+    ...options.map(x => z.literal(x)),
+    z.pipe(z.string(), z.transform(x => unrecognized(x))),
+  ] as any);
+}
+
+export function inboundSchemaInt<T extends Record<string, number | string>>(
+  enumObj: T,
+): z.ZodMiniType<OpenEnum<T>, unknown> {
+  // For numeric enums, Object.values returns both numbers and string keys
+  const options = Object.values(enumObj).filter(v => typeof v === "number");
+  return z.union([
+    ...options.map(x => z.literal(x)),
+    z.pipe(z.int(), z.transform(x => unrecognized(x))),
+  ] as any);
+}
+
+export function outboundSchema<T extends Record<string, string>>(
+  _: T,
+): z.ZodMiniType<string, OpenEnum<T>> {
+  return z.string() as any;
+}
+
+export function outboundSchemaInt<T extends Record<string, number | string>>(
+  _: T,
+): z.ZodMiniType<number, OpenEnum<T>> {
+  return z.int() as any;
+}

package/src/types/fp.ts

@@ -0,0 +1,50 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+/**
+ * A monad that captures the result of a function call or an error if it was not
+ * successful. Railway programming, enabled by this type, can be a nicer
+ * alternative to traditional exception throwing because it allows functions to
+ * declare all _known_ errors with static types and then check for them
+ * exhaustively in application code. Thrown exception have a type of `unknown`
+ * and break out of regular control flow of programs making them harder to
+ * inspect and more verbose work with due to try-catch blocks.
+ */
+export type Result<T, E = unknown> =
+  | { ok: true; value: T; error?: never }
+  | { ok: false; value?: never; error: E };
+
+export function OK<V>(value: V): Result<V, never> {
+  return { ok: true, value };
+}
+
+export function ERR<E>(error: E): Result<never, E> {
+  return { ok: false, error };
+}
+
+/**
+ * unwrap is a convenience function for extracting a value from a result or
+ * throwing if there was an error.
+ */
+export function unwrap<T>(r: Result<T, unknown>): T {
+  if (!r.ok) {
+    throw r.error;
+  }
+  return r.value;
+}
+
+/**
+ * unwrapAsync is a convenience function for resolving a value from a Promise
+ * of a result or rejecting if an error occurred.
+ */
+export async function unwrapAsync<T>(
+  pr: Promise<Result<T, unknown>>,
+): Promise<T> {
+  const r = await pr;
+  if (!r.ok) {
+    throw r.error;
+  }
+
+  return r.value;
+}

package/src/types/index.ts

@@ -0,0 +1,13 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+export { blobLikeSchema, isBlobLike } from "./blobs.js";
+export * from "./default-to-zero-value.js";
+export type { ClosedEnum, OpenEnum } from "./enums.js";
+export type { Result } from "./fp.js";
+export type { PageIterator, Paginator } from "./operations.js";
+export { createPageIterator } from "./operations.js";
+export * from "./primitives.js";
+export { RFCDate } from "./rfcdate.js";
+export * from "./unrecognized.js";

package/src/types/operations.ts

@@ -0,0 +1,105 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { Result } from "./fp.js";
+
+export type Paginator<V> = () => Promise<V & { next: Paginator<V> }> | null;
+
+export type PageIterator<V, PageState = unknown> = V & {
+  next: Paginator<V>;
+  [Symbol.asyncIterator]: () => AsyncIterableIterator<V>;
+  "~next"?: PageState | undefined;
+};
+
+export function createPageIterator<V>(
+  page: V & { next: Paginator<V> },
+  halt: (v: V) => boolean,
+): {
+  [Symbol.asyncIterator]: () => AsyncIterableIterator<V>;
+} {
+  return {
+    [Symbol.asyncIterator]: async function* paginator() {
+      yield page;
+      if (halt(page)) {
+        return;
+      }
+
+      let p: typeof page | null = page;
+      for (p = await p.next(); p != null; p = await p.next()) {
+        yield p;
+        if (halt(p)) {
+          return;
+        }
+      }
+    },
+  };
+}
+
+/**
+ * This utility create a special iterator that yields a single value and
+ * terminates. It is useful in paginated SDK functions that have early return
+ * paths when things go wrong.
+ */
+export function haltIterator<V extends object>(
+  v: V,
+): PageIterator<V, undefined> {
+  return {
+    ...v,
+    next: () => null,
+    [Symbol.asyncIterator]: async function* paginator() {
+      yield v;
+    },
+  };
+}
+
+/**
+ * Converts an async iterator of `Result<V, E>` into an async iterator of `V`.
+ * When error results occur, the underlying error value is thrown.
+ */
+export async function unwrapResultIterator<V, PageState>(
+  iteratorPromise: Promise<PageIterator<Result<V, unknown>, PageState>>,
+): Promise<PageIterator<V, PageState>> {
+  const resultIter = await iteratorPromise;
+
+  if (!resultIter.ok) {
+    throw resultIter.error;
+  }
+
+  return {
+    ...resultIter.value,
+    next: unwrapPaginator(resultIter.next),
+    "~next": resultIter["~next"],
+    [Symbol.asyncIterator]: async function* paginator() {
+      for await (const page of resultIter) {
+        if (!page.ok) {
+          throw page.error;
+        }
+        yield page.value;
+      }
+    },
+  };
+}
+
+function unwrapPaginator<V>(
+  paginator: Paginator<Result<V, unknown>>,
+): Paginator<V> {
+  return () => {
+    const nextResult = paginator();
+    if (nextResult == null) {
+      return null;
+    }
+    return nextResult.then((res) => {
+      if (!res.ok) {
+        throw res.error;
+      }
+      const out = {
+        ...res.value,
+        next: unwrapPaginator(res.next),
+      };
+      return out;
+    });
+  };
+}
+
+export const URL_OVERRIDE = Symbol("URL_OVERRIDE");

package/src/types/primitives.ts

@@ -0,0 +1,168 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v4-mini";
+import { defaultToZeroValue } from "./default-to-zero-value.js";
+import { unrecognized } from "./unrecognized.js";
+
+export function string(): z.ZodMiniType<string> {
+  return z.union([
+    z.string(),
+
+    // Null or undefined -> ""
+    zodDefaultToZeroValue(""),
+
+    // Any other value -> String(x)
+    z.pipe(z.any(), z.transform((x) => unrecognized(JSON.stringify(x)))),
+  ]);
+}
+
+export function boolean(): z.ZodMiniType<boolean> {
+  return z.union([
+    z.boolean(),
+
+    // String "true" (case insensitive) -> true, "false" -> false
+    z.pipe(
+      z.string(),
+      z.transform((x, ctx) => {
+        const lower = x.toLowerCase();
+        if (lower === "true") return unrecognized(true);
+        if (lower === "false") return unrecognized(false);
+        ctx.issues.push({
+          input: x,
+          code: "invalid_type",
+          expected: "boolean",
+          received: "string",
+        });
+        return z.NEVER;
+      }),
+    ),
+
+    zodDefaultToZeroValue(false),
+  ]);
+}
+
+export function number(): z.ZodMiniType<number> {
+  return z.union([
+    z.number(),
+
+    // String -> Number
+    z.pipe(
+      z.string(),
+      z.transform((x, ctx) => {
+        const num = Number(x);
+        if (isNaN(num)) {
+          ctx.issues.push({
+            input: x,
+            code: "invalid_type",
+            expected: "number",
+            received: "string",
+          });
+          return z.NEVER;
+        }
+        return unrecognized(num);
+      }),
+    ),
+
+    // Null or undefined -> 0
+    zodDefaultToZeroValue(0),
+  ]);
+}
+
+export function bigint(): z.ZodMiniType<bigint> {
+  return z.union([
+    z.pipe(
+      z.string(),
+      z.transform((x, ctx) => {
+        try {
+          return BigInt(x);
+        } catch (error) {
+          ctx.issues.push({
+            input: x,
+            code: "invalid_type",
+            expected: "bigint",
+            received: "string",
+          });
+          return z.NEVER;
+        }
+      }),
+    ),
+    zodDefaultToZeroValue(0n),
+  ]);
+}
+
+export function date(): z.ZodMiniType<Date> {
+  return z.union([
+    z.pipe(
+      z.pipe(
+        z.union([z.string(), zodDefaultToZeroValue(0)]),
+        z.transform((x) => new Date(x)),
+      ),
+      z.date(),
+    ),
+    z.pipe(
+      z.number(),
+      z.transform((x, ctx) => {
+        const date = new Date(x);
+        if (isNaN(date.getTime())) {
+          ctx.issues.push({
+            input: x,
+            code: "invalid_type",
+            expected: "date",
+            received: "number",
+          });
+          return z.NEVER;
+        }
+        return unrecognized(date);
+      }),
+    ),
+  ]);
+}
+
+export function literal<T extends string | number | boolean>(
+  value: T,
+): z.ZodMiniType<T> {
+  return z.union([z.literal(value), zodDefaultToZeroValue(value)]);
+}
+
+export function literalBigInt<T extends bigint>(value: T): z.ZodMiniType<T> {
+  return z.pipe(z.literal(String(value)), z.transform((x) => BigInt(x))) as any;
+}
+
+export function optional<T extends z.ZodMiniType>(t: T) {
+  return z.union([
+    z.undefined(),
+
+    // Null -> undefined
+    z.pipe(z.null(), z.transform(() => unrecognized(undefined))),
+    t,
+  ]);
+}
+
+export function nullable<T extends z.ZodMiniType>(t: T) {
+  return z.union([
+    z.null(),
+
+    // Undefined -> null
+    z.pipe(z.undefined(), z.transform(() => defaultToZeroValue(null))),
+    t,
+  ]);
+}
+
+function zodDefaultToZeroValue<T>(value: T): z.ZodMiniType<T> {
+  return z.pipe(
+    z.any(),
+    z.transform((input, ctx) => {
+      if (input === undefined) return defaultToZeroValue(value);
+      if (input === null) return defaultToZeroValue(value);
+      ctx.issues.push({
+        input: input,
+        code: "invalid_type",
+        expected: "undefined",
+        received: "unknown",
+      });
+      return z.NEVER;
+    }),
+  );
+}

package/src/types/rfcdate.ts

@@ -0,0 +1,54 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+const dateRE = /^\d{4}-\d{2}-\d{2}$/;
+
+export class RFCDate {
+  private serialized: string;
+
+  /**
+   * Creates a new RFCDate instance using today's date.
+   */
+  static today(): RFCDate {
+    return new RFCDate(new Date());
+  }
+
+  /**
+   * Creates a new RFCDate instance using the provided input.
+   * If a string is used then in must be in the format YYYY-MM-DD.
+   *
+   * @param date A Date object or a date string in YYYY-MM-DD format
+   * @example
+   * new RFCDate("2022-01-01")
+   * @example
+   * new RFCDate(new Date())
+   */
+  constructor(date: Date | string) {
+    if (typeof date === "string" && !dateRE.test(date)) {
+      throw new RangeError(
+        "RFCDate: date strings must be in the format YYYY-MM-DD: " + date,
+      );
+    }
+
+    const value = new Date(date);
+    if (isNaN(+value)) {
+      throw new RangeError("RFCDate: invalid date provided: " + date);
+    }
+
+    this.serialized = value.toISOString().slice(0, "YYYY-MM-DD".length);
+    if (!dateRE.test(this.serialized)) {
+      throw new TypeError(
+        `RFCDate: failed to build valid date with given value: ${date} serialized to ${this.serialized}`,
+      );
+    }
+  }
+
+  toJSON(): string {
+    return this.toString();
+  }
+
+  toString(): string {
+    return this.serialized;
+  }
+}

package/src/types/smart-union.ts

@@ -0,0 +1,146 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+// Not needed if lax mode
+import * as z from "zod/v4-mini";
+import { startCountingDefaultToZeroValue } from "./default-to-zero-value.js";
+import { isUnknown as isDiscriminatedUnionUnknown } from "./discriminated-union.js";
+import { RFCDate } from "./rfcdate.js";
+import { startCountingUnrecognized } from "./unrecognized.js";
+
+interface Candidate {
+  data: unknown;
+  /** Total number of fields in the parsed data */
+  fieldCount: number;
+  /** Number of fields which only matched due to lax parsing */
+  inexactCount: number;
+  /** Number of fields which defaulted to zero values */
+  zeroDefaultCount: number;
+}
+
+/**
+ * Smart union parser that tries all schemas and returns the best match
+ * based on the number of populated fields.
+ */
+export function smartUnion<
+  Options extends readonly [z.ZodMiniType, z.ZodMiniType, ...z.ZodMiniType[]],
+>(
+  options: Options,
+): z.ZodMiniType<z.output<Options[number]>, z.input<Options[number]>> {
+  return z.pipe(
+    z.unknown(),
+    z.transform((input, ctx) => {
+      const candidates: Candidate[] = [];
+      const errors: z.core.$ZodIssue[][] = options.map(() => []);
+
+      const parentUnrecognizedCtr = startCountingUnrecognized();
+      const parentZeroDefaultCtr = startCountingDefaultToZeroValue();
+
+      // Filter out invalid options
+      for (const [i, option] of options.entries()) {
+        const unrecognizedCtr = startCountingUnrecognized();
+        const zeroDefaultCtr = startCountingDefaultToZeroValue();
+        const result = option.safeParse(input);
+        const inexactCount = unrecognizedCtr.end();
+        const zeroDefaultCount = zeroDefaultCtr.end();
+        if (result.success) {
+          candidates.push({
+            data: result.data,
+            inexactCount,
+            zeroDefaultCount,
+            fieldCount: -1, // We'll count this later if needed
+          });
+          continue;
+        }
+        errors[i]!.push(...result.error.issues);
+      }
+
+      // No valid options
+      if (candidates.length === 0) {
+        parentUnrecognizedCtr.end(0);
+        parentZeroDefaultCtr.end(0);
+        ctx.issues.push({
+          input: input,
+          code: "invalid_union",
+          errors: errors,
+        });
+        return z.NEVER;
+      }
+
+      let best = candidates[0]!;
+
+      // Find the best option
+      for (const candidate of candidates) {
+        // Minor optimization to avoid counting fields if there's only one candidate
+        if (candidates.length > 1) {
+          candidate.fieldCount = countFieldsRecursive(candidate.data);
+        }
+        best = better(candidate, best);
+      }
+
+      // The cost of this union should be the cost of the best candidate not all the candidates
+      parentUnrecognizedCtr.end(best.inexactCount);
+      parentZeroDefaultCtr.end(best.zeroDefaultCount);
+
+      return best.data;
+    }),
+  ) as any;
+}
+
+function better(a: Candidate, b: Candidate): Candidate {
+  const actualFieldCountA = a.fieldCount - a.zeroDefaultCount;
+  const actualFieldCountB = b.fieldCount - b.zeroDefaultCount;
+  if (actualFieldCountA !== actualFieldCountB) {
+    return actualFieldCountA > actualFieldCountB ? a : b;
+  }
+  return a.inexactCount < b.inexactCount ? a : b;
+}
+
+/**
+ * Counts the number of fields in a parsed value recursively.
+ * @param `parsed` assumed to *not* contain cycles
+ * fieldCount: total number of fields found
+ * inexactCount: number of primitive values that are not unrecognized enum values
+ */
+function countFieldsRecursive(parsed: unknown): number {
+  let fieldCount = 0;
+
+  const queue: unknown[] = [parsed];
+  let index = 0;
+
+  while (index < queue.length) {
+    const value = queue[index++];
+    if (value === undefined || isDiscriminatedUnionUnknown(value)) {
+      continue;
+    }
+
+    // Check if it's a primitive value
+    const type = typeof value;
+    if (
+      value === null
+      || type === "number"
+      || type === "string"
+      || type === "boolean"
+      || type === "bigint"
+      || value instanceof Date
+      || value instanceof RFCDate
+    ) {
+      fieldCount++;
+      continue;
+    }
+
+    // Handle arrays
+    if (Array.isArray(value)) {
+      queue.push(...value);
+      continue;
+    }
+
+    // Handle objects
+    if (type === "object") {
+      queue.push(...Object.values(value));
+    }
+  }
+
+  return fieldCount;
+}

package/src/types/streams.ts

@@ -0,0 +1,21 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+export function isReadableStream<T = Uint8Array>(
+  val: unknown,
+): val is ReadableStream<T> {
+  if (typeof val !== "object" || val === null) {
+    return false;
+  }
+
+  // Check for the presence of methods specific to ReadableStream
+  const stream = val as ReadableStream<Uint8Array>;
+
+  // ReadableStream has methods like getReader, cancel, and tee
+  return (
+    typeof stream.getReader === "function" &&
+    typeof stream.cancel === "function" &&
+    typeof stream.tee === "function"
+  );
+}