@ominity/api-typescript 0.0.1

package/src/models/errors/documentation.ts

@@ -0,0 +1,50 @@
+/*
+ * SDK error documentation link model.
+ */
+
+import * as z from "zod/v4";
+import { safeParse } from "../../lib/schemas.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import { SDKValidationError } from "./sdk-validation-error.js";
+
+/**
+ * The URL to the API error handling guide.
+ */
+export type Documentation = {
+  href: string;
+  type: string;
+};
+
+/** @internal */
+export const Documentation$inboundSchema: z.ZodType<Documentation, unknown> = z
+  .object({
+    href: z.string(),
+    type: z.string(),
+  });
+/** @internal */
+export type Documentation$Outbound = {
+  href: string;
+  type: string;
+};
+
+/** @internal */
+export const Documentation$outboundSchema: z.ZodType<
+  Documentation$Outbound,
+  Documentation
+> = z.object({
+  href: z.string(),
+  type: z.string(),
+});
+
+export function documentationToJSON(documentation: Documentation): string {
+  return JSON.stringify(Documentation$outboundSchema.parse(documentation));
+}
+export function documentationFromJSON(
+  jsonString: string,
+): SafeParseResult<Documentation, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => Documentation$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'Documentation' from JSON`,
+  );
+}

package/src/models/errors/error-response-links.ts

@@ -0,0 +1,58 @@
+/*
+ * SDK error response links model.
+ */
+
+import * as z from "zod/v4";
+import { safeParse } from "../../lib/schemas.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import { SDKValidationError } from "./sdk-validation-error.js";
+import {
+  Documentation,
+  Documentation$inboundSchema,
+  Documentation$outboundSchema,
+  Documentation$Outbound,
+} from "./documentation.js";
+
+export type ErrorResponseLinks = {
+  /**
+   * The URL to the API error handling guide.
+   */
+  documentation: Documentation;
+};
+
+/** @internal */
+export const ErrorResponseLinks$inboundSchema: z.ZodType<
+  ErrorResponseLinks,
+  unknown
+> = z.object({
+  documentation: z.lazy(() => Documentation$inboundSchema),
+});
+/** @internal */
+export type ErrorResponseLinks$Outbound = {
+  documentation: Documentation$Outbound;
+};
+
+/** @internal */
+export const ErrorResponseLinks$outboundSchema: z.ZodType<
+  ErrorResponseLinks$Outbound,
+  ErrorResponseLinks
+> = z.object({
+  documentation: z.lazy(() => Documentation$outboundSchema),
+});
+
+export function errorResponseLinksToJSON(
+  errorResponseLinks: ErrorResponseLinks,
+): string {
+  return JSON.stringify(
+    ErrorResponseLinks$outboundSchema.parse(errorResponseLinks),
+  );
+}
+export function errorResponseLinksFromJSON(
+  jsonString: string,
+): SafeParseResult<ErrorResponseLinks, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => ErrorResponseLinks$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'ErrorResponseLinks' from JSON`,
+  );
+}

package/src/models/errors/error-response.ts

@@ -0,0 +1,121 @@
+/*
+ * SDK error response model.
+ */
+
+import * as z from "zod/v4";
+import { remap as remap$ } from "../../lib/primitives.js";
+import * as types from "../../types/primitives.js";
+import { OminityError } from "./ominity-error.js";
+import {
+  ErrorResponseLinks,
+  ErrorResponseLinks$inboundSchema,
+  ErrorResponseLinks$Outbound,
+} from "./error-response-links.js";
+
+/**
+ * An error response object.
+ */
+export type ErrorResponseData = {
+  /**
+   * The status code of the error message. This is always the same code as the
+   * status code of the HTTP message itself.
+   */
+  status: number;
+  /**
+   * The HTTP reason phrase of the error.
+   */
+  title: string;
+  /**
+   * A detailed human-readable description of the error that occurred.
+   */
+  detail: string;
+  /**
+   * Optional validation errors keyed by field name.
+   */
+  fields?: Record<string, string[]> | undefined;
+  links: ErrorResponseLinks;
+};
+
+/**
+ * An error response object.
+ */
+export class ErrorResponse extends OminityError {
+  status: number;
+  title: string;
+  detail: string;
+  fields?: Record<string, string[]> | undefined;
+  links: ErrorResponseLinks;
+
+  /** The original data that was passed to this error instance. */
+  data$: ErrorResponseData;
+
+  constructor(
+    err: ErrorResponseData,
+    httpMeta: { response: Response; request: Request; body: string },
+  ) {
+    const message = "message" in err && typeof err.message === "string"
+      ? err.message
+      : `API error occurred: ${JSON.stringify(err)}`;
+    super(message, httpMeta);
+    this.data$ = err;
+    this.status = err.status;
+    this.title = err.title;
+    this.detail = err.detail;
+    if (err.fields != null) this.fields = err.fields;
+    this.links = err.links;
+
+    this.name = "ErrorResponse";
+  }
+}
+
+const ErrorResponseFieldsSchema = z.record(z.string(), z.array(z.string()));
+
+/** @internal */
+export const ErrorResponse$inboundSchema: z.ZodType<
+  ErrorResponse,
+  unknown
+> = z.object({
+  status: types.number(),
+  title: types.string(),
+  detail: types.string(),
+  fields: z.optional(ErrorResponseFieldsSchema),
+  _links: z.lazy(() => ErrorResponseLinks$inboundSchema),
+  request$: z.custom<Request>(x => x instanceof Request),
+  response$: z.custom<Response>(x => x instanceof Response),
+  body$: z.string(),
+}).transform((v) => {
+  const remapped = remap$(v, {
+    "_links": "links",
+  });
+
+  return new ErrorResponse(remapped, {
+    request: v.request$,
+    response: v.response$,
+    body: v.body$,
+  });
+});
+
+/** @internal */
+export type ErrorResponse$Outbound = {
+  status: number;
+  title: string;
+  detail: string;
+  fields?: Record<string, string[]> | undefined;
+  _links: ErrorResponseLinks$Outbound;
+};
+
+/** @internal */
+export const ErrorResponse$outboundSchema: z.ZodType<
+  ErrorResponse$Outbound,
+  ErrorResponse
+> = z.custom<ErrorResponse>(v => v instanceof ErrorResponse)
+  .transform((v): ErrorResponse$Outbound => {
+    const data = v.data$;
+    return {
+      status: data.status,
+      title: data.title,
+      detail: data.detail,
+      fields: data.fields,
+      _links: data.links,
+    };
+  });

package/src/models/errors/http-client-errors.ts

@@ -0,0 +1,58 @@
+/**
+ * Base class for all HTTP errors.
+ */
+export class HTTPClientError extends Error {
+  /** The underlying cause of the error. */
+  override readonly cause: unknown;
+  override name = "HTTPClientError";
+  constructor(message: string, opts?: { cause?: unknown }) {
+    let msg = message;
+    if (opts?.cause) {
+      msg += `: ${opts.cause}`;
+    }
+
+    super(msg, opts);
+    // In older runtimes, the cause field would not have been assigned through
+    // the super() call.
+    if (typeof this.cause === "undefined") {
+      this.cause = opts?.cause;
+    }
+  }
+}
+
+/**
+ * An error to capture unrecognised or unexpected errors when making HTTP calls.
+ */
+export class UnexpectedClientError extends HTTPClientError {
+  override name = "UnexpectedClientError";
+}
+
+/**
+ * An error that is raised when any inputs used to create a request are invalid.
+ */
+export class InvalidRequestError extends HTTPClientError {
+  override name = "InvalidRequestError";
+}
+
+/**
+ * An error that is raised when a HTTP request was aborted by the client error.
+ */
+export class RequestAbortedError extends HTTPClientError {
+  override readonly name = "RequestAbortedError";
+}
+
+/**
+ * An error that is raised when a HTTP request timed out due to an AbortSignal
+ * signal timeout.
+ */
+export class RequestTimeoutError extends HTTPClientError {
+  override readonly name = "RequestTimeoutError";
+}
+
+/**
+ * An error that is raised when a HTTP client is unable to make a request to
+ * a server.
+ */
+export class ConnectionError extends HTTPClientError {
+  override readonly name = "ConnectionError";
+}

package/src/models/errors/index.ts

@@ -0,0 +1,8 @@
+export * from "./documentation.js";
+export * from "./error-response-links.js";
+export * from "./error-response.js";
+export * from "./http-client-errors.js";
+export * from "./ominity-default-error.js";
+export * from "./ominity-error.js";
+export * from "./response-validation-error.js";
+export * from "./sdk-validation-error.js";

package/src/models/errors/ominity-default-error.ts

@@ -0,0 +1,36 @@
+import { OminityError } from "./ominity-error.js";
+
+/** The fallback error class if no more specific error class is matched */
+export class OminityDefaultError extends OminityError {
+  constructor(
+    message: string,
+    httpMeta: {
+      response: Response;
+      request: Request;
+      body: string;
+    },
+  ) {
+    if (message) {
+      message += `: `;
+    }
+    message += `Status ${httpMeta.response.status}`;
+    const contentType = httpMeta.response.headers.get("content-type") || `""`;
+    if (contentType !== "application/json") {
+      message += ` Content-Type ${
+        contentType.includes(" ") ? `"${contentType}"` : contentType
+      }`;
+    }
+    const body = httpMeta.body || `""`;
+    message += body.length > 100 ? "\n" : ". ";
+    let bodyDisplay = body;
+    if (body.length > 10000) {
+      const truncated = body.substring(0, 10000);
+      const remaining = body.length - 10000;
+      bodyDisplay = `${truncated}...and ${remaining} more chars`;
+    }
+    message += `Body: ${bodyDisplay}`;
+    message = message.trim();
+    super(message, httpMeta);
+    this.name = "OminityDefaultError";
+  }
+}

package/src/models/errors/ominity-error.ts

@@ -0,0 +1,31 @@
+/** The base class for all HTTP error responses */
+export class OminityError extends Error {
+  /** HTTP status code */
+  public readonly statusCode: number;
+  /** HTTP body */
+  public readonly body: string;
+  /** HTTP headers */
+  public readonly headers: Headers;
+  /** HTTP content type */
+  public readonly contentType: string;
+  /** Raw response */
+  public readonly rawResponse: Response;
+
+  constructor(
+    message: string,
+    httpMeta: {
+      response: Response;
+      request: Request;
+      body: string;
+    },
+  ) {
+    super(message);
+    this.statusCode = httpMeta.response.status;
+    this.body = httpMeta.body;
+    this.headers = httpMeta.response.headers;
+    this.contentType = httpMeta.response.headers.get("content-type") || "";
+    this.rawResponse = httpMeta.response;
+
+    this.name = "OminityError";
+  }
+}

package/src/models/errors/response-validation-error.ts

@@ -0,0 +1,46 @@
+import * as z from "zod/v4";
+import { OminityError } from "./ominity-error.js";
+import { formatZodError } from "./sdk-validation-error.js";
+
+export class ResponseValidationError extends OminityError {
+  /**
+   * The raw value that failed validation.
+   */
+  public readonly rawValue: unknown;
+
+  /**
+   * The raw message that failed validation.
+   */
+  public readonly rawMessage: unknown;
+
+  constructor(
+    message: string,
+    extra: {
+      response: Response;
+      request: Request;
+      body: string;
+      cause: unknown;
+      rawValue: unknown;
+      rawMessage: unknown;
+    },
+  ) {
+    super(message, extra);
+    this.name = "ResponseValidationError";
+    this.cause = extra.cause;
+    this.rawValue = extra.rawValue;
+    this.rawMessage = extra.rawMessage;
+  }
+
+  /**
+   * Return a pretty-formatted error message if the underlying validation error
+   * is a ZodError or some other recognized error type, otherwise return the
+   * default error message.
+   */
+  public pretty(): string {
+    if (this.cause instanceof z.ZodError) {
+      return `${this.rawMessage}\n${formatZodError(this.cause)}`;
+    } else {
+      return this.toString();
+    }
+  }
+}

package/src/models/errors/sdk-validation-error.ts

@@ -0,0 +1,50 @@
+import * as z from "zod/v4";
+
+export class SDKValidationError extends Error {
+  /**
+   * The raw value that failed validation.
+   */
+  public readonly rawValue: unknown;
+
+  /**
+   * The raw message that failed validation.
+   */
+  public readonly rawMessage: unknown;
+
+  // Allows for backwards compatibility for `instanceof` checks of `ResponseValidationError`
+  static override [Symbol.hasInstance](
+    instance: unknown,
+  ): instance is SDKValidationError {
+    if (!(instance instanceof Error)) return false;
+    if (!("rawValue" in instance)) return false;
+    if (!("rawMessage" in instance)) return false;
+    if (!("pretty" in instance)) return false;
+    if (typeof instance.pretty !== "function") return false;
+    return true;
+  }
+
+  constructor(message: string, cause: unknown, rawValue: unknown) {
+    super(`${message}: ${cause}`);
+    this.name = "SDKValidationError";
+    this.cause = cause;
+    this.rawValue = rawValue;
+    this.rawMessage = message;
+  }
+
+  /**
+   * Return a pretty-formatted error message if the underlying validation error
+   * is a ZodError or some other recognized error type, otherwise return the
+   * default error message.
+   */
+  public pretty(): string {
+    if (this.cause instanceof z.ZodError) {
+      return `${this.rawMessage}\n${formatZodError(this.cause)}`;
+    } else {
+      return this.toString();
+    }
+  }
+}
+
+export function formatZodError(err: z.ZodError): string {
+  return z.prettifyError(err);
+}

package/src/models/index.ts

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

package/src/models/operations/index.ts

@@ -0,0 +1,2 @@
+// Operation models will be defined as the SDK endpoints are implemented.
+export {};

package/src/models/security.ts

@@ -0,0 +1,46 @@
+import * as z from "zod/v4";
+import { safeParse } from "../lib/schemas.js";
+import { Result as SafeParseResult } from "../types/fp.js";
+import { SDKValidationError } from "./errors/sdk-validation-error.js";
+
+export type Security = {
+  apiKey?: string | undefined;
+  oAuth?: string | undefined;
+};
+
+/** @internal */
+export const Security$inboundSchema: z.ZodType<Security, unknown> = z
+  .object({
+    apiKey: z.optional(z.string()),
+    oAuth: z.optional(z.string()),
+  });
+/** @internal */
+export type Security$Outbound = {
+  apiKey?: string | undefined;
+  oAuth?: string | undefined;
+};
+
+/** @internal */
+export const Security$outboundSchema: z.ZodType<
+  Security$Outbound,
+  Security
+> = z.pipe(
+  z.object({
+    apiKey: z.optional(z.string()),
+    oAuth: z.optional(z.string()),
+  }),
+  z.transform((v) => v),
+);
+
+export function securityToJSON(security: Security): string {
+  return JSON.stringify(Security$outboundSchema.parse(security));
+}
+export function securityFromJSON(
+  jsonString: string,
+): SafeParseResult<Security, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => Security$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'Security' from JSON`,
+  );
+}

package/src/sdk/cms/index.ts

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

package/src/sdk/commerce/index.ts

@@ -0,0 +1,13 @@
+/*
+ * SDK module: Commerce
+ */
+
+import { ClientSDK } from "../../lib/sdks.js";
+import { Products } from "./products.js";
+
+export class Commerce extends ClientSDK {
+  private _products?: Products;
+  get products(): Products {
+    return (this._products ??= new Products(this._options));
+  }
+}

package/src/sdk/commerce/products.ts

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