@ominity/api-typescript 0.0.1

package/src/sdk/http.ts

@@ -0,0 +1,204 @@
+/*
+ * SDK module: Generic HTTP access
+ */
+
+import { HookContext } from "../hooks/types.js";
+import { encodeForm } from "../lib/encodings.js";
+import { RetryConfig } from "../lib/retries.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { ClientSDK, RequestOptions } from "../lib/sdks.js";
+import * as models from "../models/index.js";
+
+export type HttpQuery =
+  | string
+  | URLSearchParams
+  | Record<string, unknown>
+  | undefined;
+
+export type HttpRequestOptions = RequestOptions & {
+  query?: HttpQuery;
+  json?: unknown;
+  body?: RequestInit["body"];
+  security?: models.Security | (() => Promise<models.Security>) | undefined;
+  errorCodes?: Array<number | string>;
+};
+
+function isBodyInit(value: unknown): value is RequestInit["body"] {
+  return value === null
+    || typeof value === "string"
+    || value instanceof ArrayBuffer
+    || value instanceof Uint8Array
+    || value instanceof Blob
+    || value instanceof FormData
+    || value instanceof URLSearchParams
+    || value instanceof ReadableStream;
+}
+
+function buildQuery(query: HttpQuery): string | undefined {
+  if (!query) return;
+  if (typeof query === "string") return query;
+  if (query instanceof URLSearchParams) return query.toString();
+
+  const parts: string[] = [];
+  for (const [key, value] of Object.entries(query)) {
+    const encoded = encodeForm(key, value, { charEncoding: "percent" });
+    if (typeof encoded !== "undefined" && encoded !== "") {
+      parts.push(encoded);
+    }
+  }
+
+  return parts.join("&");
+}
+
+function resolveRetryConfig(
+  options?: RequestOptions,
+  fallback?: RetryConfig,
+): RetryConfig {
+  return options?.retries ?? fallback ?? { strategy: "none" };
+}
+
+export class Http extends ClientSDK {
+  async request(
+    method: string,
+    path: string,
+    options?: HttpRequestOptions,
+  ): Promise<Response> {
+    const {
+      query,
+      json,
+      security,
+      errorCodes,
+      serverURL,
+      retries,
+      retryCodes,
+      headers,
+      body,
+      fetchOptions,
+      timeoutMs,
+      ...rest
+    } = options ?? {};
+
+    const resolvedQuery = buildQuery(query);
+    const resolvedSecuritySource = security ?? this._options.security;
+    const resolvedSecurity = resolveGlobalSecurity(
+      await extractSecurity(resolvedSecuritySource),
+    );
+
+    const resolvedHeaders = new Headers(headers ?? fetchOptions?.headers);
+    let resolvedBody: RequestInit["body"] | undefined;
+
+    if (typeof json !== "undefined") {
+      resolvedBody = JSON.stringify(json);
+      if (!resolvedHeaders.has("content-type")) {
+        resolvedHeaders.set("Content-Type", "application/json");
+      }
+    } else if (typeof body !== "undefined") {
+      if (isBodyInit(body)) {
+        resolvedBody = body;
+      } else {
+        resolvedBody = JSON.stringify(body);
+        if (!resolvedHeaders.has("content-type")) {
+          resolvedHeaders.set("Content-Type", "application/json");
+        }
+      }
+    }
+
+    const retryConfig = resolveRetryConfig(options, this._options.retryConfig);
+    const finalRetryCodes = retryCodes ?? ["429", "5XX"];
+    const finalErrorCodes = errorCodes ?? ["4XX", "5XX"];
+
+    const baseURL = serverURL ?? this._baseURL ?? undefined;
+    const context: HookContext = {
+      baseURL: baseURL ?? "",
+      operationID: "http.request",
+      oAuth2Scopes: null,
+      securitySource: resolvedSecuritySource,
+      retryConfig,
+      resolvedSecurity,
+      options: this._options,
+    };
+
+    const requestConfig: {
+      method: string;
+      path: string;
+      baseURL?: string | URL | undefined;
+      query?: string;
+      body?: RequestInit["body"];
+      security?: ReturnType<typeof resolveGlobalSecurity>;
+      uaHeader?: string;
+      userAgent?: string | undefined;
+      timeoutMs?: number;
+    } = {
+      method: method.toUpperCase(),
+      path,
+      security: resolvedSecurity,
+      uaHeader: "user-agent",
+    };
+
+    if (baseURL) requestConfig.baseURL = baseURL;
+    if (resolvedQuery) requestConfig.query = resolvedQuery;
+    if (typeof resolvedBody !== "undefined") requestConfig.body = resolvedBody;
+    if (typeof this._options.userAgent !== "undefined") {
+      requestConfig.userAgent = this._options.userAgent;
+    }
+    const effectiveTimeout = timeoutMs ?? this._options.timeoutMs;
+    if (typeof effectiveTimeout !== "undefined") {
+      requestConfig.timeoutMs = effectiveTimeout;
+    }
+
+    const requestOptions: RequestOptions = {
+      ...rest,
+      headers: resolvedHeaders,
+    };
+    if (fetchOptions) requestOptions.fetchOptions = fetchOptions;
+    if (typeof retries !== "undefined") requestOptions.retries = retries;
+    if (typeof finalRetryCodes !== "undefined") {
+      requestOptions.retryCodes = finalRetryCodes;
+    }
+    if (typeof timeoutMs !== "undefined") requestOptions.timeoutMs = timeoutMs;
+    if (typeof serverURL !== "undefined") requestOptions.serverURL = serverURL;
+
+    const req = this._createRequest(
+      context,
+      requestConfig,
+      requestOptions,
+    );
+
+    if (!req.ok) {
+      throw req.error;
+    }
+
+    const response = await this._do(req.value, {
+      context,
+      errorCodes: finalErrorCodes,
+      retryConfig,
+      retryCodes: finalRetryCodes,
+    });
+
+    if (!response.ok) {
+      throw response.error;
+    }
+
+    return response.value;
+  }
+
+  get(path: string, options?: HttpRequestOptions): Promise<Response> {
+    return this.request("GET", path, options);
+  }
+
+  post(path: string, options?: HttpRequestOptions): Promise<Response> {
+    return this.request("POST", path, options);
+  }
+
+  put(path: string, options?: HttpRequestOptions): Promise<Response> {
+    return this.request("PUT", path, options);
+  }
+
+  patch(path: string, options?: HttpRequestOptions): Promise<Response> {
+    return this.request("PATCH", path, options);
+  }
+
+  delete(path: string, options?: HttpRequestOptions): Promise<Response> {
+    return this.request("DELETE", path, options);
+  }
+}

package/src/sdk/index.ts

@@ -0,0 +1,2 @@
+
+export * from "./sdk.js";

package/src/sdk/sdk.ts

@@ -0,0 +1,28 @@
+
+import { ClientSDK } from "../lib/sdks.js";
+import { Cms } from "./cms/index.js";
+import { Commerce } from "./commerce/index.js";
+import { Http } from "./http.js";
+import { Settings } from "./settings/index.js";
+
+export class Ominity extends ClientSDK {
+  private _commerce?: Commerce;
+  get commerce(): Commerce {
+    return (this._commerce ??= new Commerce(this._options));
+  }
+
+  private _cms?: Cms;
+  get cms(): Cms {
+    return (this._cms ??= new Cms(this._options));
+  }
+
+  private _settings?: Settings;
+  get settings(): Settings {
+    return (this._settings ??= new Settings(this._options));
+  }
+
+  private _http?: Http;
+  get http(): Http {
+    return (this._http ??= new Http(this._options));
+  }
+}

package/src/sdk/settings/index.ts

@@ -0,0 +1,7 @@
+/*
+ * SDK module: Settings
+ */
+
+import { ClientSDK } from "../../lib/sdks.js";
+
+export class Settings extends ClientSDK {}

package/src/types/async.ts

@@ -0,0 +1,65 @@
+
+export type APICall =
+  | {
+      status: "complete";
+      request: Request;
+      response: Response;
+    }
+  | {
+      status: "request-error";
+      request: Request;
+      response?: undefined;
+    }
+  | {
+      status: "invalid";
+      request?: undefined;
+      response?: undefined;
+    };
+
+export class APIPromise<T> implements Promise<T> {
+  readonly #promise: Promise<[T, APICall]>;
+  readonly #unwrapped: Promise<T>;
+
+  readonly [Symbol.toStringTag] = "APIPromise";
+
+  constructor(p: [T, APICall] | Promise<[T, APICall]>) {
+    this.#promise = p instanceof Promise ? p : Promise.resolve(p);
+    this.#unwrapped =
+      p instanceof Promise
+        ? this.#promise.then(([value]) => value)
+        : Promise.resolve(p[0]);
+  }
+
+  then<TResult1 = T, TResult2 = never>(
+    onfulfilled?:
+      | ((value: T) => TResult1 | PromiseLike<TResult1>)
+      | null
+      | undefined,
+    onrejected?:
+      | ((reason: any) => TResult2 | PromiseLike<TResult2>)
+      | null
+      | undefined,
+  ): Promise<TResult1 | TResult2> {
+    return this.#promise.then(
+      onfulfilled ? ([value]) => onfulfilled(value) : void 0,
+      onrejected,
+    );
+  }
+
+  catch<TResult = never>(
+    onrejected?:
+      | ((reason: any) => TResult | PromiseLike<TResult>)
+      | null
+      | undefined,
+  ): Promise<T | TResult> {
+    return this.#unwrapped.catch(onrejected);
+  }
+
+  finally(onfinally?: (() => void) | null | undefined): Promise<T> {
+    return this.#unwrapped.finally(onfinally);
+  }
+
+  $inspect(): Promise<[T, APICall]> {
+    return this.#promise;
+  }
+}

package/src/types/blobs.ts

@@ -0,0 +1,30 @@
+
+import * as z from "zod/v4";
+
+export const blobLikeSchema: z.ZodType<Blob, Blob> = z.custom<Blob>(
+  isBlobLike,
+  {
+    message: "expected a Blob, File or Blob-like object",
+    abort: true,
+  },
+);
+
+export function isBlobLike(val: unknown): val is Blob {
+  if (val instanceof Blob) {
+    return true;
+  }
+
+  if (typeof val !== "object" || val == null || !(Symbol.toStringTag in val)) {
+    return false;
+  }
+
+  const name = val[Symbol.toStringTag];
+  if (typeof name !== "string") {
+    return false;
+  }
+  if (name !== "Blob" && name !== "File") {
+    return false;
+  }
+
+  return "stream" in val && typeof val.stream === "function";
+}

package/src/types/const-date-time.ts

@@ -0,0 +1,12 @@
+
+import * as z from "zod/v4";
+
+export function constDateTime(
+  val: string,
+): z.ZodType<string, unknown> {
+  return z.custom<string>((v) => {
+    return (
+      typeof v === "string" && new Date(v).getTime() === new Date(val).getTime()
+    );
+  }, `Value must be equivalent to ${val}`);
+}

package/src/types/default-to-zero-value.ts

@@ -0,0 +1,30 @@
+
+import { type Unrecognized, unrecognized } from "./unrecognized.js";
+
+let globalCount = 0;
+let refCount = 0;
+
+export function defaultToZeroValue<T>(value: T): Unrecognized<T> {
+  globalCount++;
+  return unrecognized(value);
+}
+
+export function startCountingDefaultToZeroValue() {
+  refCount++;
+  const start = globalCount;
+  return {
+    /**
+     * Ends counting and returns the delta.
+     * @param delta - If provided, only this amount is added to the parent counter
+     *   (used for nested unions where we only want to record the winning option's count).
+     *   If not provided, records all counts since start().
+     */
+    end: (delta?: number) => {
+      const count = globalCount - start;
+      // Reset globalCount back to start, then add only the specified delta
+      globalCount = start + (delta ?? count);
+      if (--refCount === 0) globalCount = 0;
+      return count;
+    },
+  };
+}

package/src/types/enums.ts

@@ -0,0 +1,42 @@
+
+import * as z from "zod/v4";
+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.ZodType<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.ZodType<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.ZodType<string, OpenEnum<T>> {
+  return z.string() as any;
+}
+
+export function outboundSchemaInt<T extends Record<string, number | string>>(
+  _: T,
+): z.ZodType<number, OpenEnum<T>> {
+  return z.int() as any;
+}

package/src/types/fp.ts

@@ -0,0 +1,47 @@
+
+/**
+ * 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,10 @@
+
+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,102 @@
+
+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");