@apollo-deploy/tesseract 0.4.4 → 0.5.0

package/dist/collector.d.ts

@@ -0,0 +1,135 @@
+/**
+ * SDKCollector — framework-agnostic route and domain collector.
+ *
+ * The core primitive behind all framework adapters. Accumulates route
+ * definitions and domain metadata, then builds a `BackendManifest` in memory
+ * and calls the Tesseract generator.
+ *
+ * Used directly for framework-agnostic workflows and internally by all
+ * framework adapters (Express, Hono, Koa, Elysia, NestJS).
+ *
+ * ```ts
+ * import { SDKCollector } from '@apollo-deploy/tesseract';
+ *
+ * const collector = new SDKCollector({
+ *   info: { title: 'My API', version: '1.0.0', baseUrl: 'https://api.example.com' },
+ *   output: './packages/api-sdk',
+ * });
+ *
+ * collector.domain('/users', { domain: 'users', description: 'User management' });
+ * collector.route('/users/:id', 'GET', { sdk: { methodName: 'getUser' } });
+ * collector.route('/users', 'POST', { sdk: { methodName: 'createUser' } });
+ *
+ * if (process.env.TESSERACT_GENERATE) {
+ *   await collector.generate();
+ *   process.exit(0);
+ * }
+ * ```
+ */
+import type { BackendManifest, ManifestRouteSchema } from './types/manifest.js';
+import type { SDKModuleConfig, SDKRouteConfig } from './types/sdk-module.js';
+export interface CollectorOptions {
+    /** API metadata written into the generated package.json and README. */
+    info: {
+        title: string;
+        version: string;
+        baseUrl?: string;
+        description?: string;
+    };
+    /** Output directory for the generated SDK. */
+    output: string;
+    /**
+     * Shared type package used across your backend and generated SDK.
+     *
+     * When set, bare `$ref` values in route schemas (e.g. `{ $ref: 'User' }`)
+     * are treated as type names from this package rather than generating them inline.
+     */
+    schemaPackage?: {
+        name: string;
+        version?: string;
+        importPath?: string;
+    };
+    /** `'functional'` (default) or `'class'` (Resend-style `new MySDK('key')`). */
+    sdkStyle?: 'functional' | 'class';
+    /** `'internal'` (default) or `'public'` (auth key only, baseUrl baked in). */
+    clientType?: 'internal' | 'public';
+    /** Override the generated npm package name. */
+    packageName?: string;
+    /** Override the generated package version. */
+    packageVersion?: string;
+}
+export interface CollectorRouteConfig {
+    /** JSON Schemas for params, querystring, body, headers, and response. */
+    schema?: ManifestRouteSchema;
+    /** SDK-specific options for this route. */
+    sdk: SDKRouteConfig;
+    /** Whether the route is a Server-Sent Events stream. */
+    sse?: boolean;
+}
+interface InternalRoute {
+    url: string;
+    method: string;
+    schema?: ManifestRouteSchema;
+    sdk: SDKRouteConfig;
+    sse?: boolean;
+}
+/**
+ * Framework-agnostic route and domain collector.
+ *
+ * Works with any Node.js HTTP framework — Express, Hono, Koa, Elysia, NestJS,
+ * or plain `node:http`. Framework-specific subpackages export pre-wired
+ * subclasses or helpers that build on this class.
+ */
+export declare class SDKCollector {
+    protected readonly _routes: InternalRoute[];
+    protected readonly _registry: Map<string, SDKModuleConfig>;
+    readonly opts: Readonly<CollectorOptions>;
+    constructor(opts: CollectorOptions);
+    /**
+     * Declare a domain (route group) by its URL prefix.
+     *
+     * @param prefix - The URL prefix shared by all routes in this domain (e.g. `/users`).
+     * @param config - Optional domain metadata — name override, description, stability.
+     */
+    domain(prefix: string, config?: Omit<SDKModuleConfig, 'prefix'>): this;
+    /**
+     * Register a route with the collector.
+     *
+     * Routes with `sdk.exclude: true` are silently ignored.
+     *
+     * @param url    - Full URL path, e.g. `/users/:id`.
+     * @param method - HTTP method (case-insensitive).
+     * @param config - Schema and SDK options for this route.
+     */
+    route(url: string, method: string, config: CollectorRouteConfig): this;
+    /** Build and return the `BackendManifest` from all accumulated routes and domains. */
+    buildManifest(): BackendManifest;
+    /** Generate the SDK from accumulated routes and domains. */
+    generate(): Promise<import('./index.js').GenerateResult>;
+    /**
+     * Check if `TESSERACT_GENERATE=1` is set and generate the SDK if so.
+     *
+     * Returns `true` if generation was triggered. Call after all routes have
+     * been registered:
+     *
+     * ```ts
+     * // At the bottom of your app setup file:
+     * if (await collector.tryGenerate()) process.exit(0);
+     * ```
+     */
+    tryGenerate(): Promise<boolean>;
+}
+/**
+ * Builds a `BackendManifest` from a flat list of collected routes and a domain
+ * registry. Exported so framework adapters (including the Fastify plugin) can
+ * use it directly without going through `SDKCollector`.
+ */
+export declare function buildManifestFromRoutes(routes: ReadonlyArray<{
+    url: string;
+    method: string;
+    schema?: ManifestRouteSchema;
+    sdk: SDKRouteConfig;
+    sse?: boolean;
+}>, registry: ReadonlyMap<string, SDKModuleConfig>, info: CollectorOptions['info'], schemaPackage?: CollectorOptions['schemaPackage']): BackendManifest;
+export {};
+//# sourceMappingURL=collector.d.ts.map

package/dist/collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../src/collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAiB,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/F,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE7E,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,IAAI,EAAE;QACJ,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,aAAa,CAAC,EAAE;QACd,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC;IAClC,8EAA8E;IAC9E,UAAU,CAAC,EAAE,UAAU,GAAG,QAAQ,CAAC;IACnC,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,yEAAyE;IACzE,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,2CAA2C;IAC3C,GAAG,EAAE,cAAc,CAAC;IACpB,wDAAwD;IACxD,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,UAAU,aAAa;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,GAAG,EAAE,cAAc,CAAC;IACpB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;;;;;GAMG;AACH,qBAAa,YAAY;IACvB,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,aAAa,EAAE,CAAM;IACjD,SAAS,CAAC,QAAQ,CAAC,SAAS,+BAAsC;IAClE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;gBAE9B,IAAI,EAAE,gBAAgB;IAIlC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAC,GAAG,IAAI;IAKtE;;;;;;;;OAQG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,GAAG,IAAI;IAYtE,sFAAsF;IACtF,aAAa,IAAI,eAAe;IAIhC,4DAA4D;IACtD,QAAQ,IAAI,OAAO,CAAC,OAAO,YAAY,EAAE,cAAc,CAAC;IAa9D;;;;;;;;;;OAUG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;CAStC;AAID;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,aAAa,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,GAAG,EAAE,cAAc,CAAC;IACpB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,CAAC,EACF,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,EAC9C,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,EAC9B,aAAa,CAAC,EAAE,gBAAgB,CAAC,eAAe,CAAC,GAChD,eAAe,CAuCjB"}

package/dist/collector.js

@@ -0,0 +1,159 @@
+/**
+ * SDKCollector — framework-agnostic route and domain collector.
+ *
+ * The core primitive behind all framework adapters. Accumulates route
+ * definitions and domain metadata, then builds a `BackendManifest` in memory
+ * and calls the Tesseract generator.
+ *
+ * Used directly for framework-agnostic workflows and internally by all
+ * framework adapters (Express, Hono, Koa, Elysia, NestJS).
+ *
+ * ```ts
+ * import { SDKCollector } from '@apollo-deploy/tesseract';
+ *
+ * const collector = new SDKCollector({
+ *   info: { title: 'My API', version: '1.0.0', baseUrl: 'https://api.example.com' },
+ *   output: './packages/api-sdk',
+ * });
+ *
+ * collector.domain('/users', { domain: 'users', description: 'User management' });
+ * collector.route('/users/:id', 'GET', { sdk: { methodName: 'getUser' } });
+ * collector.route('/users', 'POST', { sdk: { methodName: 'createUser' } });
+ *
+ * if (process.env.TESSERACT_GENERATE) {
+ *   await collector.generate();
+ *   process.exit(0);
+ * }
+ * ```
+ */
+/**
+ * Framework-agnostic route and domain collector.
+ *
+ * Works with any Node.js HTTP framework — Express, Hono, Koa, Elysia, NestJS,
+ * or plain `node:http`. Framework-specific subpackages export pre-wired
+ * subclasses or helpers that build on this class.
+ */
+export class SDKCollector {
+    _routes = [];
+    _registry = new Map();
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /**
+     * Declare a domain (route group) by its URL prefix.
+     *
+     * @param prefix - The URL prefix shared by all routes in this domain (e.g. `/users`).
+     * @param config - Optional domain metadata — name override, description, stability.
+     */
+    domain(prefix, config) {
+        this._registry.set(prefix, { prefix, ...config });
+        return this;
+    }
+    /**
+     * Register a route with the collector.
+     *
+     * Routes with `sdk.exclude: true` are silently ignored.
+     *
+     * @param url    - Full URL path, e.g. `/users/:id`.
+     * @param method - HTTP method (case-insensitive).
+     * @param config - Schema and SDK options for this route.
+     */
+    route(url, method, config) {
+        if (config.sdk?.exclude)
+            return this;
+        this._routes.push({
+            url,
+            method: method.toUpperCase(),
+            schema: config.schema,
+            sdk: config.sdk,
+            sse: config.sse,
+        });
+        return this;
+    }
+    /** Build and return the `BackendManifest` from all accumulated routes and domains. */
+    buildManifest() {
+        return buildManifestFromRoutes(this._routes, this._registry, this.opts.info, this.opts.schemaPackage);
+    }
+    /** Generate the SDK from accumulated routes and domains. */
+    async generate() {
+        const { generate } = await import('./index.js');
+        const manifest = this.buildManifest();
+        return generate({
+            manifest,
+            output: this.opts.output,
+            clientType: this.opts.clientType,
+            packageName: this.opts.packageName,
+            packageVersion: this.opts.packageVersion,
+            sdkStyle: this.opts.sdkStyle,
+        });
+    }
+    /**
+     * Check if `TESSERACT_GENERATE=1` is set and generate the SDK if so.
+     *
+     * Returns `true` if generation was triggered. Call after all routes have
+     * been registered:
+     *
+     * ```ts
+     * // At the bottom of your app setup file:
+     * if (await collector.tryGenerate()) process.exit(0);
+     * ```
+     */
+    async tryGenerate() {
+        if (!process.env.TESSERACT_GENERATE)
+            return false;
+        const result = await this.generate();
+        if (result.warnings.length > 0) {
+            for (const w of result.warnings)
+                console.warn(`  ⚠  ${w}`);
+        }
+        console.log(`[tesseract] ✓ ${result.filesWritten} files written → ${this.opts.output}`);
+        return true;
+    }
+}
+// ── Shared manifest builder ───────────────────────────────────────────────────
+/**
+ * Builds a `BackendManifest` from a flat list of collected routes and a domain
+ * registry. Exported so framework adapters (including the Fastify plugin) can
+ * use it directly without going through `SDKCollector`.
+ */
+export function buildManifestFromRoutes(routes, registry, info, schemaPackage) {
+    // Longest-prefix-first so more specific prefixes match before their parents
+    const sortedPrefixes = [...registry.keys()].sort((a, b) => b.length - a.length);
+    const domainMap = new Map();
+    for (const route of routes) {
+        const matchedPrefix = sortedPrefixes.find((p) => route.url === p || route.url.startsWith(p + '/')) ??
+            derivePrefix(route.url);
+        if (!domainMap.has(matchedPrefix)) {
+            domainMap.set(matchedPrefix, {
+                config: registry.get(matchedPrefix) ?? { prefix: matchedPrefix },
+                routes: [],
+            });
+        }
+        const tail = route.url.substring(matchedPrefix.length) || '/';
+        domainMap.get(matchedPrefix).routes.push({
+            method: route.method,
+            url: tail.startsWith('/') ? tail : '/' + tail,
+            schema: route.schema,
+            sdk: route.sdk,
+            sse: route.sse,
+        });
+    }
+    return {
+        $schema: 'sdk-manifold/v1',
+        info: {
+            title: info.title,
+            version: info.version,
+            description: info.description,
+            baseUrl: info.baseUrl,
+        },
+        ...(schemaPackage && { schemaPackage }),
+        domains: [...domainMap.values()].map(({ config, routes }) => ({ ...config, routes })),
+    };
+}
+/** Derives a domain prefix from the first non-parameter URL segment. */
+function derivePrefix(url) {
+    const first = url.split('/').find((s) => s.length > 0 && !s.startsWith(':'));
+    return first ? '/' + first : '/';
+}
+//# sourceMappingURL=collector.js.map

package/dist/collector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.js","sourceRoot":"","sources":["../src/collector.ts"],"names":[],"mappings":"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"}

package/dist/elysia.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Tesseract Elysia integration.
+ *
+ * Provides a `tesseractPlugin()` factory that returns an Elysia plugin and a
+ * paired `SDKCollector`. Register the plugin with your app, then annotate
+ * routes with the collector. The plugin triggers SDK generation automatically
+ * when `TESSERACT_GENERATE=1` is set.
+ *
+ * ```ts
+ * import { Elysia } from 'elysia';
+ * import { tesseractPlugin } from '@apollo-deploy/tesseract/elysia';
+ *
+ * const { plugin, collector } = tesseractPlugin({
+ *   info: { title: 'My API', version: '1.0.0', baseUrl: 'https://api.example.com' },
+ *   output: './packages/api-sdk',
+ * });
+ *
+ * collector.domain('/users', { domain: 'users', description: 'User management' });
+ * collector.route('/users/:id', 'GET', { sdk: { methodName: 'getUser' } });
+ * collector.route('/users', 'POST', { sdk: { methodName: 'createUser' } });
+ *
+ * const app = new Elysia()
+ *   .use(plugin)
+ *   .get('/users/:id', ({ params }) => getUser(params.id))
+ *   .post('/users', ({ body }) => createUser(body))
+ *   .listen(3000);
+ * ```
+ *
+ * **Triggering generation:**
+ * ```bash
+ * TESSERACT_GENERATE=1 bun run dist/app.js
+ * ```
+ */
+import { SDKCollector } from './collector.js';
+import type { CollectorOptions } from './collector.js';
+export { SDKCollector } from './collector.js';
+export type { CollectorOptions, CollectorRouteConfig } from './collector.js';
+/**
+ * Minimal Elysia plugin type — typed as `unknown` to avoid requiring a hard
+ * dependency on the `elysia` package.
+ */
+type ElysiaLike = {
+    onStart(handler: () => void | Promise<void>): unknown;
+};
+export interface TesseractElysiaPlugin {
+    /** The Elysia plugin. Pass to `.use(plugin)` on your app. */
+    plugin: (app: ElysiaLike) => ElysiaLike;
+    /** The collector. Register domains and routes on this before your app starts. */
+    collector: SDKCollector;
+}
+/**
+ * Create a Tesseract Elysia plugin and a paired `SDKCollector`.
+ *
+ * The plugin registers an `onStart` hook that triggers SDK generation when
+ * `TESSERACT_GENERATE=1` is set. It is a no-op otherwise.
+ *
+ * @example
+ * ```ts
+ * const { plugin, collector } = tesseractPlugin({ info: { ... }, output: './sdk' });
+ * collector.route('/users/:id', 'GET', { sdk: { methodName: 'getUser' } });
+ * new Elysia().use(plugin).get('/users/:id', handler).listen(3000);
+ * ```
+ */
+export declare function tesseractPlugin(opts: CollectorOptions): TesseractElysiaPlugin;
+//# sourceMappingURL=elysia.d.ts.map

package/dist/elysia.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elysia.d.ts","sourceRoot":"","sources":["../src/elysia.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE7E;;;GAGG;AACH,KAAK,UAAU,GAAG;IAChB,OAAO,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;CACvD,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,MAAM,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,UAAU,CAAC;IACxC,iFAAiF;IACjF,SAAS,EAAE,YAAY,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG,qBAAqB,CA2B7E"}

package/dist/elysia.js

@@ -0,0 +1,70 @@
+/**
+ * Tesseract Elysia integration.
+ *
+ * Provides a `tesseractPlugin()` factory that returns an Elysia plugin and a
+ * paired `SDKCollector`. Register the plugin with your app, then annotate
+ * routes with the collector. The plugin triggers SDK generation automatically
+ * when `TESSERACT_GENERATE=1` is set.
+ *
+ * ```ts
+ * import { Elysia } from 'elysia';
+ * import { tesseractPlugin } from '@apollo-deploy/tesseract/elysia';
+ *
+ * const { plugin, collector } = tesseractPlugin({
+ *   info: { title: 'My API', version: '1.0.0', baseUrl: 'https://api.example.com' },
+ *   output: './packages/api-sdk',
+ * });
+ *
+ * collector.domain('/users', { domain: 'users', description: 'User management' });
+ * collector.route('/users/:id', 'GET', { sdk: { methodName: 'getUser' } });
+ * collector.route('/users', 'POST', { sdk: { methodName: 'createUser' } });
+ *
+ * const app = new Elysia()
+ *   .use(plugin)
+ *   .get('/users/:id', ({ params }) => getUser(params.id))
+ *   .post('/users', ({ body }) => createUser(body))
+ *   .listen(3000);
+ * ```
+ *
+ * **Triggering generation:**
+ * ```bash
+ * TESSERACT_GENERATE=1 bun run dist/app.js
+ * ```
+ */
+import { SDKCollector } from './collector.js';
+export { SDKCollector } from './collector.js';
+/**
+ * Create a Tesseract Elysia plugin and a paired `SDKCollector`.
+ *
+ * The plugin registers an `onStart` hook that triggers SDK generation when
+ * `TESSERACT_GENERATE=1` is set. It is a no-op otherwise.
+ *
+ * @example
+ * ```ts
+ * const { plugin, collector } = tesseractPlugin({ info: { ... }, output: './sdk' });
+ * collector.route('/users/:id', 'GET', { sdk: { methodName: 'getUser' } });
+ * new Elysia().use(plugin).get('/users/:id', handler).listen(3000);
+ * ```
+ */
+export function tesseractPlugin(opts) {
+    const collector = new SDKCollector(opts);
+    const plugin = (app) => {
+        app.onStart(async () => {
+            if (!process.env.TESSERACT_GENERATE)
+                return;
+            if (collector['_routes'].length === 0) {
+                console.error('\n[tesseract] No SDK routes found. Call collector.route() before the app starts.');
+                process.exit(1);
+            }
+            const result = await collector.generate();
+            for (const w of result.warnings)
+                console.warn(`  ⚠  ${w}`);
+            console.log(`\n[tesseract] ${collector['_routes'].length} route(s) → ${opts.output}`);
+            console.log(`[tesseract] ✓ ${result.filesWritten} files written\n`);
+            process.exit(0);
+        });
+        return app;
+    };
+    return { plugin, collector };
+}
+//# sourceMappingURL=elysia.js.map

package/dist/elysia.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"elysia.js","sourceRoot":"","sources":["../src/elysia.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAkB9C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAAC,IAAsB;IACpD,MAAM,SAAS,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IAEzC,MAAM,MAAM,GAAG,CAAC,GAAe,EAAc,EAAE;QAC7C,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE;YACrB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB;gBAAE,OAAO;YAE5C,IAAI,SAAS,CAAC,SAAS,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACtC,OAAO,CAAC,KAAK,CACX,kFAAkF,CACnF,CAAC;gBACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YAED,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,QAAQ,EAAE,CAAC;YAC1C,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ;gBAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;YAC3D,OAAO,CAAC,GAAG,CACT,iBAAiB,SAAS,CAAC,SAAS,CAAC,CAAC,MAAM,eAAe,IAAI,CAAC,MAAM,EAAE,CACzE,CAAC;YACF,OAAO,CAAC,GAAG,CAAC,iBAAiB,MAAM,CAAC,YAAY,kBAAkB,CAAC,CAAC;YACpE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC,CAAC,CAAC;QAEH,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;IAEF,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAC/B,CAAC"}

package/dist/express.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Tesseract Express integration.
+ *
+ * Re-exports `SDKCollector` and adds an `ExpressSDKCollector` subclass with a
+ * `.expressRoute()` helper that registers a route with the collector and returns
+ * a no-op Express middleware in a single call — keeping SDK metadata co-located
+ * with the route definition.
+ *
+ * Because Express has no route-registration hook, routes are registered with the
+ * collector explicitly. Generation is triggered by calling
+ * `collector.tryGenerate()` after all routes are set up.
+ *
+ * ```ts
+ * import express from 'express';
+ * import { ExpressSDKCollector } from '@apollo-deploy/tesseract/express';
+ *
+ * const app = express();
+ * const collector = new ExpressSDKCollector({
+ *   info: { title: 'My API', version: '1.0.0', baseUrl: 'https://api.example.com' },
+ *   output: './packages/api-sdk',
+ * });
+ *
+ * collector.domain('/users', { domain: 'users', description: 'User management' });
+ *
+ * app.get('/users/:id',
+ *   collector.expressRoute('/users/:id', 'GET', { sdk: { methodName: 'getUser' } }),
+ *   getUserHandler,
+ * );
+ *
+ * app.post('/users',
+ *   collector.expressRoute('/users', 'POST', { sdk: { methodName: 'createUser' } }),
+ *   createUserHandler,
+ * );
+ *
+ * // After all routes are registered:
+ * if (await collector.tryGenerate()) process.exit(0);
+ *
+ * app.listen(3000);
+ * ```
+ *
+ * **Triggering generation:**
+ * ```bash
+ * TESSERACT_GENERATE=1 node dist/app.js
+ * ```
+ */
+import { SDKCollector } from './collector.js';
+import type { CollectorRouteConfig } from './collector.js';
+/** Minimal Express RequestHandler type — avoids a hard import of the `express` package. */
+type RequestHandler = (req: unknown, res: unknown, next: () => void) => void;
+export { SDKCollector } from './collector.js';
+export type { CollectorOptions, CollectorRouteConfig } from './collector.js';
+/**
+ * `SDKCollector` subclass with an Express-specific `.expressRoute()` helper.
+ *
+ * `.expressRoute()` registers a route with the collector **and** returns a
+ * no-op `RequestHandler` for inline placement in `app.get()` / `router.post()` etc.
+ */
+export declare class ExpressSDKCollector extends SDKCollector {
+    /**
+     * Register a route with the collector and return a no-op Express middleware.
+     *
+     * Placing the returned middleware in your route definition keeps the SDK
+     * metadata co-located with the handler:
+     *
+     * ```ts
+     * app.get('/users/:id', collector.expressRoute('/users/:id', 'GET', {
+     *   sdk: { methodName: 'getUser' },
+     *   schema: { response: { 200: { $ref: 'User' } } },
+     * }), handler);
+     * ```
+     */
+    expressRoute(url: string, method: string, config: CollectorRouteConfig): RequestHandler;
+}
+//# sourceMappingURL=express.d.ts.map

package/dist/express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../src/express.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,2FAA2F;AAC3F,KAAK,cAAc,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAE7E,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE7E;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IACnD;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,GAAG,cAAc;CAIxF"}

package/dist/express.js

@@ -0,0 +1,73 @@
+/**
+ * Tesseract Express integration.
+ *
+ * Re-exports `SDKCollector` and adds an `ExpressSDKCollector` subclass with a
+ * `.expressRoute()` helper that registers a route with the collector and returns
+ * a no-op Express middleware in a single call — keeping SDK metadata co-located
+ * with the route definition.
+ *
+ * Because Express has no route-registration hook, routes are registered with the
+ * collector explicitly. Generation is triggered by calling
+ * `collector.tryGenerate()` after all routes are set up.
+ *
+ * ```ts
+ * import express from 'express';
+ * import { ExpressSDKCollector } from '@apollo-deploy/tesseract/express';
+ *
+ * const app = express();
+ * const collector = new ExpressSDKCollector({
+ *   info: { title: 'My API', version: '1.0.0', baseUrl: 'https://api.example.com' },
+ *   output: './packages/api-sdk',
+ * });
+ *
+ * collector.domain('/users', { domain: 'users', description: 'User management' });
+ *
+ * app.get('/users/:id',
+ *   collector.expressRoute('/users/:id', 'GET', { sdk: { methodName: 'getUser' } }),
+ *   getUserHandler,
+ * );
+ *
+ * app.post('/users',
+ *   collector.expressRoute('/users', 'POST', { sdk: { methodName: 'createUser' } }),
+ *   createUserHandler,
+ * );
+ *
+ * // After all routes are registered:
+ * if (await collector.tryGenerate()) process.exit(0);
+ *
+ * app.listen(3000);
+ * ```
+ *
+ * **Triggering generation:**
+ * ```bash
+ * TESSERACT_GENERATE=1 node dist/app.js
+ * ```
+ */
+import { SDKCollector } from './collector.js';
+export { SDKCollector } from './collector.js';
+/**
+ * `SDKCollector` subclass with an Express-specific `.expressRoute()` helper.
+ *
+ * `.expressRoute()` registers a route with the collector **and** returns a
+ * no-op `RequestHandler` for inline placement in `app.get()` / `router.post()` etc.
+ */
+export class ExpressSDKCollector extends SDKCollector {
+    /**
+     * Register a route with the collector and return a no-op Express middleware.
+     *
+     * Placing the returned middleware in your route definition keeps the SDK
+     * metadata co-located with the handler:
+     *
+     * ```ts
+     * app.get('/users/:id', collector.expressRoute('/users/:id', 'GET', {
+     *   sdk: { methodName: 'getUser' },
+     *   schema: { response: { 200: { $ref: 'User' } } },
+     * }), handler);
+     * ```
+     */
+    expressRoute(url, method, config) {
+        this.route(url, method, config);
+        return (_req, _res, next) => next();
+    }
+}
+//# sourceMappingURL=express.js.map

package/dist/express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.js","sourceRoot":"","sources":["../src/express.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAM9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C;;;;;GAKG;AACH,MAAM,OAAO,mBAAoB,SAAQ,YAAY;IACnD;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,GAAW,EAAE,MAAc,EAAE,MAA4B;QACpE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAChC,OAAO,CAAC,IAAa,EAAE,IAAa,EAAE,IAAgB,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;IACpE,CAAC;CACF"}