apiwork 0.0.2 → 0.0.4

package/dist/bin/apiwork.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bin/apiwork.js

@@ -4,16 +4,16 @@ import {
 } from "../chunk-7NDS6XB6.js";
 import {
   generate
-} from "../chunk-ZP6ZWEPI.js";
+} from "../chunk-HDAQOD6F.js";
 import {
   generate as generate2
-} from "../chunk-4AJOYIJC.js";
+} from "../chunk-XVH7TUYP.js";
 import {
   generate as generate3
-} from "../chunk-NQPUJJ3O.js";
+} from "../chunk-6T7CXXXA.js";
 import {
   writeFiles
-} from "../chunk-QGKZLUZR.js";
+} from "../chunk-KUY3DEBX.js";
 import "../chunk-MWFEILAW.js";
 
 // src/cli.ts

package/dist/{chunk-NQPUJJ3O.js → chunk-6T7CXXXA.js}

@@ -3,7 +3,7 @@ import {
   buildSchemas,
   buildScopeIndex,
   resolveGenerateOptions
-} from "./chunk-QGKZLUZR.js";
+} from "./chunk-KUY3DEBX.js";
 
 // src/zod/generate.ts
 function generate(schema, options = {}) {

package/dist/{chunk-ZP6ZWEPI.js → chunk-HDAQOD6F.js}

@@ -7,7 +7,7 @@ import {
   resolveDomainIdentifier,
   resolveEndpointIdentifier,
   resolveGenerateOptions
-} from "./chunk-QGKZLUZR.js";
+} from "./chunk-KUY3DEBX.js";
 import {
   camelCase
 } from "./chunk-MWFEILAW.js";

package/dist/{chunk-QGKZLUZR.js → chunk-KUY3DEBX.js}

@@ -63,7 +63,7 @@ var TYPE_MAP = {
   boolean: "z.boolean()",
   date: "z.iso.date()",
   datetime: "z.iso.datetime()",
-  decimal: "z.number()",
+  decimal: "z.coerce.number()",
   integer: "z.number().int()",
   number: "z.number()",
   string: "z.string()",
@@ -288,7 +288,7 @@ function serializeDefault(param) {
     return "''";
   }
   if (typeof value === "string") {
-    return `'${value}'`;
+    return param.type === "decimal" ? value : `'${value}'`;
   }
   if (typeof value === "boolean" || typeof value === "number") {
     return String(value);
@@ -660,7 +660,7 @@ function generateDefinitionType(parts) {
   if (parts.errorCodes.length > 0) {
     fields.push(`errors: ${typeName}Errors`);
   }
-  return `export interface ${typeName} { ${fields.join("; ")} }`;
+  return `export interface ${typeName} { ${fields.join("; ")}; }`;
 }
 function generateActionSchemas(parts, lines, references, context) {
   const { typeName } = parts;

package/dist/{chunk-4AJOYIJC.js → chunk-XVH7TUYP.js}

@@ -3,7 +3,7 @@ import {
   buildSchemas,
   buildScopeIndex,
   resolveGenerateOptions
-} from "./chunk-QGKZLUZR.js";
+} from "./chunk-KUY3DEBX.js";
 
 // src/typescript/generate.ts
 function generate(schema, options = {}) {

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+import { S as Schema } from './options-BDcqBI1C.js';
+export { A as Action, a as ActionMethod, b as ActionRequest, c as ActionResponse, d as ArrayParam, B as BinaryParam, e as BooleanParam, D as DateParam, f as DatetimeParam, g as DecimalParam, E as Enum, h as ErrorCode, F as FileCase, G as GenerateOptions, I as IdentifierSource, i as Info, j as InfoContact, k as InfoLicense, l as InfoServer, m as IntegerParam, L as LiteralParam, N as NumberParam, O as ObjectParam, n as ObjectType, P as Param, R as RecordParam, o as ReferenceParam, p as Resource, q as StringParam, T as TimeParam, r as Type, U as UnionParam, s as UnionType, t as UnknownParam, u as UuidParam } from './options-BDcqBI1C.js';
+
+/**
+ * Thrown when an Apiwork schema fails to parse.
+ *
+ * The {@link Error.cause} property contains the underlying error, such as a
+ * network failure from `fetch` or a `SyntaxError` from invalid JSON.
+ *
+ * @example
+ * ```ts
+ * import { parse, ParseError } from 'apiwork';
+ *
+ * try {
+ *   const schema = await parse.url('http://localhost:3000/api/v1/.apiwork');
+ * } catch (error) {
+ *   if (error instanceof ParseError) {
+ *     console.error(error.message);
+ *     console.error(error.cause);
+ *   }
+ * }
+ * ```
+ */
+declare class ParseError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Parses an Apiwork schema from raw JSON data.
+ *
+ * @param data - The raw schema data.
+ * @returns The parsed schema with camelCase keys.
+ *
+ * @example
+ * ```ts
+ * import { parse } from 'apiwork';
+ *
+ * const schema = parse(data);
+ * console.log(schema.basePath);
+ * ```
+ */
+declare function parseData(data: unknown): Schema;
+/**
+ * Fetches and parses an Apiwork schema from a URL.
+ *
+ * @param url - The URL to fetch the `.apiwork` JSON from.
+ * @returns The parsed schema with camelCase keys.
+ * @throws {@link ParseError} When the fetch fails, returns a non-OK status, or the response is not valid JSON.
+ *
+ * @example
+ * ```ts
+ * import { parse } from 'apiwork';
+ *
+ * const schema = await parse.url('http://localhost:3000/api/v1/.apiwork');
+ * ```
+ */
+declare function parseUrl(url: string): Promise<Schema>;
+/**
+ * Reads and parses an Apiwork schema from a file.
+ *
+ * @param path - The file path to the `.apiwork` JSON.
+ * @returns The parsed schema with camelCase keys.
+ * @throws {@link ParseError} When the file cannot be read or contains invalid JSON.
+ *
+ * @example
+ * ```ts
+ * import { parse } from 'apiwork';
+ *
+ * const schema = await parse.file('./schema.apiwork');
+ * ```
+ */
+declare function parseFile(path: string): Promise<Schema>;
+declare const parse: typeof parseData & {
+    file: typeof parseFile;
+    url: typeof parseUrl;
+};
+
+export { ParseError, Schema, parse };

package/dist/options-BDcqBI1C.d.ts

@@ -0,0 +1,392 @@
+/**
+ * The top-level Apiwork schema representing an API.
+ *
+ * @example
+ * ```ts
+ * import { parse } from 'apiwork';
+ *
+ * const schema = await parse.url('http://localhost:3000/api/v1/.apiwork');
+ * console.log(schema.basePath); // '/api/v1'
+ * ```
+ */
+interface Schema {
+    /** The API base path (e.g. `/api/v1`). */
+    basePath: string;
+    /** The named enum definitions. */
+    enums: Enum[];
+    /** The error codes the API may emit. */
+    errorCodes: ErrorCode[];
+    /** The stable 16-character identifier for the API. */
+    fingerprint: string;
+    /** The API metadata. `null` when unset. */
+    info: Info | null;
+    /** The locales the API supports. */
+    locales: string[];
+    /** The resources with nested actions. */
+    resources: Resource[];
+    /** The named type definitions in topological order. */
+    types: Type[];
+}
+/**
+ * A named type definition — either an object type or a discriminated union.
+ */
+type Type = ObjectType | UnionType;
+/**
+ * An object type definition with named fields.
+ */
+interface ObjectType {
+    /** Whether the type is deprecated. */
+    deprecated: boolean;
+    /** The description from metadata. `null` when unset. */
+    description: string | null;
+    /** The example value. `null` when unset. */
+    example: unknown;
+    /** The names of types this type extends. */
+    extends: string[];
+    /** The type name. */
+    name: string;
+    /** Whether the type references itself transitively. */
+    recursive: boolean;
+    /** The scope the type lives in. `null` for global scope. */
+    scope: string | null;
+    /** The fields that make up the type. */
+    shape: Param[];
+    /** The type discriminator. */
+    type: 'object';
+}
+/**
+ * A discriminated union type with variants.
+ */
+interface UnionType {
+    /** Whether the type is deprecated. */
+    deprecated: boolean;
+    /** The description from metadata. `null` when unset. */
+    description: string | null;
+    /** The discriminator field name. `null` for open unions. */
+    discriminator: string | null;
+    /** The example value. `null` when unset. */
+    example: unknown;
+    /** The type name. */
+    name: string;
+    /** Whether the type references itself transitively. */
+    recursive: boolean;
+    /** The scope the type lives in. `null` for global scope. */
+    scope: string | null;
+    /** The type discriminator. */
+    type: 'union';
+    /** The union variants. */
+    variants: Param[];
+}
+/**
+ * A parameter in a type shape, request, or response.
+ */
+type Param = ArrayParam | BinaryParam | BooleanParam | DateParam | DatetimeParam | DecimalParam | IntegerParam | LiteralParam | NumberParam | ObjectParam | RecordParam | ReferenceParam | StringParam | TimeParam | UnionParam | UnknownParam | UuidParam;
+interface ParamBase {
+    deprecated: boolean;
+    description: string | null;
+    name: string;
+    nullable: boolean;
+    optional: boolean;
+}
+interface ArrayParam extends ParamBase {
+    default?: unknown;
+    example: unknown;
+    max: number | null;
+    min: number | null;
+    of: Param | null;
+    type: 'array';
+}
+interface BinaryParam extends ParamBase {
+    default?: unknown;
+    enum: string | undefined;
+    example: unknown;
+    type: 'binary';
+}
+interface BooleanParam extends ParamBase {
+    default?: unknown;
+    enum: string | undefined;
+    example: unknown;
+    type: 'boolean';
+}
+interface DateParam extends ParamBase {
+    default?: unknown;
+    enum: string | undefined;
+    example: unknown;
+    type: 'date';
+}
+interface DatetimeParam extends ParamBase {
+    default?: unknown;
+    enum: string | undefined;
+    example: unknown;
+    type: 'datetime';
+}
+interface DecimalParam extends ParamBase {
+    default?: unknown;
+    enum: string | undefined;
+    example: unknown;
+    max: number | null;
+    min: number | null;
+    type: 'decimal';
+}
+interface IntegerParam extends ParamBase {
+    default?: unknown;
+    enum: string | undefined;
+    example: unknown;
+    format: string | null;
+    max: number | null;
+    min: number | null;
+    type: 'integer';
+}
+interface LiteralParam extends ParamBase {
+    type: 'literal';
+    value: unknown;
+}
+interface NumberParam extends ParamBase {
+    default?: unknown;
+    enum: string | undefined;
+    example: unknown;
+    max: number | null;
+    min: number | null;
+    type: 'number';
+}
+interface ObjectParam extends ParamBase {
+    partial: boolean;
+    shape: Param[];
+    type: 'object';
+}
+interface RecordParam extends ParamBase {
+    default?: unknown;
+    example: unknown;
+    of: Param | null;
+    type: 'record';
+}
+interface ReferenceParam extends ParamBase {
+    reference: string;
+    tag?: string;
+    type: 'reference';
+}
+interface StringParam extends ParamBase {
+    default?: unknown;
+    enum: string | undefined;
+    example: unknown;
+    format: string | null;
+    max: number | null;
+    min: number | null;
+    type: 'string';
+}
+interface TimeParam extends ParamBase {
+    default?: unknown;
+    enum: string | undefined;
+    example: unknown;
+    type: 'time';
+}
+interface UnionParam extends ParamBase {
+    discriminator: string | null;
+    type: 'union';
+    variants: Param[];
+}
+interface UnknownParam extends ParamBase {
+    type: 'unknown';
+}
+interface UuidParam extends ParamBase {
+    default?: unknown;
+    enum: string | undefined;
+    example: unknown;
+    type: 'uuid';
+}
+/**
+ * A resource grouping actions at a URL path.
+ */
+interface Resource {
+    /** The actions the resource exposes. */
+    actions: Action[];
+    /** The resource identifier. */
+    identifier: string;
+    /** The resource name. */
+    name: string;
+    /** The identifiers of ancestor resources. */
+    parentIdentifiers: string[];
+    /** The URL path. */
+    path: string;
+    /** The nested resources. */
+    resources: Resource[];
+    /** The scope the resource lives in. `null` for global scope. */
+    scope: string | null;
+}
+/**
+ * The HTTP method of an action.
+ */
+type ActionMethod = 'delete' | 'get' | 'patch' | 'post' | 'put';
+/**
+ * An API action at a specific HTTP method and path.
+ */
+interface Action {
+    /** Whether the action is deprecated. */
+    deprecated: boolean;
+    /** The description. `null` when unset. */
+    description: string | null;
+    /** The HTTP method. */
+    method: ActionMethod;
+    /** The action name. */
+    name: string;
+    /** The operation ID. `null` when unset. */
+    operationId: string | null;
+    /** The URL path. */
+    path: string;
+    /** The names of error codes the action may raise. */
+    raises: string[];
+    /** The request definition. */
+    request: ActionRequest;
+    /** The response definition. */
+    response: ActionResponse;
+    /** The summary. `null` when unset. */
+    summary: string | null;
+    /** The tags for grouping. */
+    tags: string[];
+}
+/**
+ * The request definition of an action.
+ */
+interface ActionRequest {
+    /** The body parameters. */
+    body: Param[];
+    /** The description. `null` when unset. */
+    description: string | null;
+    /** The query parameters. */
+    query: Param[];
+}
+/**
+ * The response definition of an action.
+ */
+interface ActionResponse {
+    /** The response body. `null` when the action returns no content. */
+    body: Param | null;
+    /** The description. `null` when unset. */
+    description: string | null;
+    /** Whether the action returns no content. */
+    noContent: boolean;
+}
+/**
+ * A named enum definition with string values.
+ */
+interface Enum {
+    /** Whether the enum is deprecated. */
+    deprecated: boolean;
+    /** The description. `null` when unset. */
+    description: string | null;
+    /** The example value. `null` when unset. */
+    example: string | null;
+    /** The enum name. */
+    name: string;
+    /** The scope the enum lives in. `null` for global scope. */
+    scope: string | null;
+    /** The allowed values. */
+    values: string[];
+}
+/**
+ * An error code the API may emit.
+ */
+interface ErrorCode {
+    /** The description. `null` when unset. */
+    description: string | null;
+    /** The error code name. */
+    name: string;
+    /** The HTTP status code. */
+    status: number;
+}
+/**
+ * The API metadata.
+ */
+interface Info {
+    /** The contact info. `null` when unset. */
+    contact: InfoContact | null;
+    /** The description. `null` when unset. */
+    description: string | null;
+    /** The license info. `null` when unset. */
+    license: InfoLicense | null;
+    /** The server URLs. */
+    servers: InfoServer[];
+    /** The summary. `null` when unset. */
+    summary: string | null;
+    /** The terms of service URL. `null` when unset. */
+    termsOfService: string | null;
+    /** The API title. `null` when unset. */
+    title: string | null;
+    /** The API version. `null` when unset. */
+    version: string | null;
+}
+/**
+ * The contact info of an API.
+ */
+interface InfoContact {
+    /** The contact email. `null` when unset. */
+    email: string | null;
+    /** The contact name. `null` when unset. */
+    name: string | null;
+    /** The contact URL. `null` when unset. */
+    url: string | null;
+}
+/**
+ * The license info of an API.
+ */
+interface InfoLicense {
+    /** The license name. `null` when unset. */
+    name: string | null;
+    /** The license URL. `null` when unset. */
+    url: string | null;
+}
+/**
+ * A server URL of an API.
+ */
+interface InfoServer {
+    /** The description. `null` when unset. */
+    description: string | null;
+    /** The server URL. `null` when unset. */
+    url: string | null;
+}
+
+/**
+ * The file name case format.
+ */
+type FileCase = 'kebab' | 'camel' | 'pascal' | 'snake';
+/**
+ * The source category of a generated identifier.
+ *
+ * - `'domain'` — types and schemas in `domains/` (scoped domain types).
+ * - `'api'` — types and schemas in `api.ts` (global domain types).
+ * - `'endpoint'` — types and schemas in `endpoints/` (request, response, definition).
+ * - `'client'` — sorbus-specific symbols: `Client`, `createClient`, `contract`.
+ *
+ * @see {@link GenerateOptions.transformIdentifier}
+ */
+type IdentifierSource = 'domain' | 'api' | 'endpoint' | 'client';
+/**
+ * Options shared by all code generators.
+ */
+interface GenerateOptions {
+    /** The file name case format. Defaults to `'kebab'`. */
+    fileCase?: FileCase;
+    /** The import path extension (e.g., `'.js'` for Node ESM). Defaults to `''`. */
+    importExtension?: '' | '.js' | '.ts';
+    /**
+     * Transforms a generated identifier into a new name.
+     *
+     * Called for every domain type, endpoint type, and client symbol the
+     * generator emits. Return `identifier` unchanged to keep the default name.
+     *
+     * @param identifier - The default identifier the generator would emit.
+     * @param source - The source category of the identifier.
+     *
+     * @example
+     * ```ts
+     * transformIdentifier: (identifier, source) => {
+     *   if (source === 'api') return `Api${identifier}`;
+     *   if (source === 'client' && identifier === 'Client') return 'MyClient';
+     *   return identifier;
+     * }
+     * ```
+     */
+    transformIdentifier?: (identifier: string, source: IdentifierSource) => string;
+}
+
+export type { Action as A, BinaryParam as B, DateParam as D, Enum as E, FileCase as F, GenerateOptions as G, IdentifierSource as I, LiteralParam as L, NumberParam as N, ObjectParam as O, Param as P, RecordParam as R, Schema as S, TimeParam as T, UnionParam as U, ActionMethod as a, ActionRequest as b, ActionResponse as c, ArrayParam as d, BooleanParam as e, DatetimeParam as f, DecimalParam as g, ErrorCode as h, Info as i, InfoContact as j, InfoLicense as k, InfoServer as l, IntegerParam as m, ObjectType as n, ReferenceParam as o, Resource as p, StringParam as q, Type as r, UnionType as s, UnknownParam as t, UuidParam as u };

package/dist/sorbus/index.d.ts

@@ -0,0 +1,49 @@
+import { G as GenerateOptions, S as Schema } from '../options-BDcqBI1C.js';
+
+/**
+ * Options for the Sorbus generator.
+ */
+interface SorbusGenerateOptions extends GenerateOptions {
+    /** TypeScript output configuration. */
+    typescript?: {
+        /** Target TypeScript major version. Defaults to `5`. */
+        version?: 5;
+    };
+    /** Target Sorbus major version. Defaults to `1`. */
+    version?: 1;
+    /** Zod output configuration. */
+    zod?: {
+        /** Target Zod major version. Defaults to `4`. */
+        version?: 4;
+    };
+}
+/**
+ * Generates Sorbus contract and client from the Apiwork schema.
+ *
+ * @param schema - The parsed schema.
+ * @param options - The generator options.
+ * @returns The generated files, keyed by file path.
+ *
+ * @example
+ * ```ts
+ * import { parse } from 'apiwork';
+ * import { generate } from 'apiwork/sorbus';
+ *
+ * const schema = await parse.url('http://localhost:3000/api/v1/.apiwork');
+ * const files = generate(schema, {
+ *   version: 1,
+ *   zod: { version: 4 },
+ *   typescript: { version: 5 },
+ *   fileCase: 'kebab',
+ *   importExtension: '.js',
+ *   transformIdentifier: (identifier, source) => {
+ *     if (source === 'api') return `Api${identifier}`;
+ *     if (source === 'client' && identifier === 'Client') return 'MyClient';
+ *     return identifier;
+ *   },
+ * });
+ * ```
+ */
+declare function generate(schema: Schema, options?: SorbusGenerateOptions): Map<string, string>;
+
+export { type SorbusGenerateOptions, generate };

package/dist/sorbus/index.js

@@ -1,7 +1,7 @@
 import {
   generate
-} from "../chunk-ZP6ZWEPI.js";
-import "../chunk-QGKZLUZR.js";
+} from "../chunk-HDAQOD6F.js";
+import "../chunk-KUY3DEBX.js";
 import "../chunk-MWFEILAW.js";
 export {
   generate

package/dist/typescript/index.d.ts

@@ -0,0 +1,36 @@
+import { G as GenerateOptions, S as Schema } from '../options-BDcqBI1C.js';
+
+/**
+ * Options for the TypeScript generator.
+ */
+interface TypescriptGenerateOptions extends GenerateOptions {
+    /** Target TypeScript major version. Defaults to `5`. */
+    version?: 5;
+}
+/**
+ * Generates TypeScript types from the Apiwork schema.
+ *
+ * @param schema - The parsed schema.
+ * @param options - The generator options.
+ * @returns The generated files, keyed by file path.
+ *
+ * @example
+ * ```ts
+ * import { parse } from 'apiwork';
+ * import { generate } from 'apiwork/typescript';
+ *
+ * const schema = await parse.url('http://localhost:3000/api/v1/.apiwork');
+ * const files = generate(schema, {
+ *   version: 5,
+ *   fileCase: 'kebab',
+ *   importExtension: '.js',
+ *   transformIdentifier: (identifier, source) => {
+ *     if (source === 'api') return `Api${identifier}`;
+ *     return identifier;
+ *   },
+ * });
+ * ```
+ */
+declare function generate(schema: Schema, options?: TypescriptGenerateOptions): Map<string, string>;
+
+export { type TypescriptGenerateOptions, generate };

package/dist/typescript/index.js

@@ -1,7 +1,7 @@
 import {
   generate
-} from "../chunk-4AJOYIJC.js";
-import "../chunk-QGKZLUZR.js";
+} from "../chunk-XVH7TUYP.js";
+import "../chunk-KUY3DEBX.js";
 import "../chunk-MWFEILAW.js";
 export {
   generate

package/dist/zod/index.d.ts

@@ -0,0 +1,42 @@
+import { G as GenerateOptions, S as Schema } from '../options-BDcqBI1C.js';
+
+/**
+ * Options for the Zod generator.
+ */
+interface ZodGenerateOptions extends GenerateOptions {
+    /** TypeScript output configuration. */
+    typescript?: {
+        /** Target TypeScript major version. Defaults to `5`. */
+        version?: 5;
+    };
+    /** Target Zod major version. Defaults to `4`. */
+    version?: 4;
+}
+/**
+ * Generates Zod schemas from the Apiwork schema.
+ *
+ * @param schema - The parsed schema.
+ * @param options - The generator options.
+ * @returns The generated files, keyed by file path.
+ *
+ * @example
+ * ```ts
+ * import { parse } from 'apiwork';
+ * import { generate } from 'apiwork/zod';
+ *
+ * const schema = await parse.url('http://localhost:3000/api/v1/.apiwork');
+ * const files = generate(schema, {
+ *   version: 4,
+ *   typescript: { version: 5 },
+ *   fileCase: 'kebab',
+ *   importExtension: '.js',
+ *   transformIdentifier: (identifier, source) => {
+ *     if (source === 'api') return `Api${identifier}`;
+ *     return identifier;
+ *   },
+ * });
+ * ```
+ */
+declare function generate(schema: Schema, options?: ZodGenerateOptions): Map<string, string>;
+
+export { type ZodGenerateOptions, generate };

package/dist/zod/index.js

@@ -1,7 +1,7 @@
 import {
   generate
-} from "../chunk-NQPUJJ3O.js";
-import "../chunk-QGKZLUZR.js";
+} from "../chunk-6T7CXXXA.js";
+import "../chunk-KUY3DEBX.js";
 import "../chunk-MWFEILAW.js";
 export {
   generate

package/package.json

@@ -11,6 +11,7 @@
     "@biomejs/biome": "2.4.12",
     "@skiftle/biome-config": "0.0.7",
     "@types/node": "25.6.0",
+    "lefthook": "2.1.2",
     "tsup": "8.5.1",
     "typescript": "6.0.2",
     "vitest": "4.1.4"
@@ -56,5 +57,5 @@
     "typecheck": "tsc --noEmit"
   },
   "type": "module",
-  "version": "0.0.2"
+  "version": "0.0.4"
 }