@tulipes/spec 0.1.0

package/README.md

@@ -0,0 +1,115 @@
+# @tulipes/spec
+
+Generates an **OpenAPI 3.1 document** and a **Postman collection** from a
+[Tulipes](https://www.npmjs.com/package/@tulipes/core) app's declared
+routes.
+
+The source is the RAI registry of a *booted* app — not parsed source — so a
+generated document describes exactly the router that is mounted. It cannot
+invent an endpoint, and it cannot miss one.
+
+```sh
+yarn add -D @tulipes/spec
+yarn tulipes spec --openapi docs/openapi.json --postman docs/collection.json
+```
+
+```
+  wrote docs/openapi.json
+  wrote docs/collection.json
+
+21 endpoint(s) across 4 folder(s): auth, hello, sessions, users
+```
+
+## Where the content comes from
+
+Everything except the request shapes is already declared:
+
+| In the document | Comes from |
+|---|---|
+| path, method | the mounted express route |
+| `operationId`, summary, description | the route's `rai({ id, name, description })` |
+| tag / folder | `rai({ folder })`, defaulting to the declaring module |
+| security, `x-tulipes-roles` | the ACL — which roles hold that permission |
+| response envelope | the framework's one response shape |
+| request/response schemas | `rai({ params, query, body, returns })` |
+
+Schemas are zod, declared on the route and **validated at runtime by the
+framework** — which is the point. A document generated from the same
+declaration that enforces the request cannot describe a shape the endpoint
+would reject.
+
+```ts
+import { z } from "zod/v4";
+
+router.post(
+  `${base}/users`,
+  rai({
+    id: "users:create",
+    name: "Create a user",
+    body: z.object({ email: z.email("emailInvalid") }),
+    returns: z.object({ id: z.string(), email: z.string() }),
+  }),
+  users.create(),
+);
+```
+
+**Use `zod/v4`.** `z.toJSONSchema` is what this package calls and it only
+understands v4 schemas. A classic `from "zod"` schema still validates, but
+produces no shape in the document — `tulipes spec` reports each one it
+could not describe rather than failing silently.
+
+## Why a Postman collection and not just the OpenAPI
+
+Postman imports OpenAPI perfectly well. A native collection carries what
+that import cannot:
+
+- **one folder per `folder`**, mirroring how the app is organised
+- `{{baseUrl}}`, `{{accessToken}}` and `{{refreshToken}}` variables, with
+  bearer auth inherited by every request
+- `noauth` on public routes, so a public endpoint is genuinely exercised
+  as the public would reach it
+- a script on the login request that **captures the token pair** — sign in
+  once and the rest of the collection is authenticated
+- example bodies built from the schemas, so a request is runnable as
+  imported rather than an empty `{}`
+
+## Programmatic use
+
+The CLI is a thin wrapper; the pieces are exported:
+
+```ts
+import { extract, toOpenApi, toPostman } from "@tulipes/spec";
+import { boot } from "@tulipes/core/boot";
+
+const handle = await boot({ rootDir, mode: "backend", listen: false });
+const source = extract(handle.ctx);
+
+const { document, warnings } = await toOpenApi(source, {
+  servers: ["https://api.example.com"],
+});
+```
+
+`listen: false` is what lets this run while the app is already serving.
+
+## Options
+
+| Flag | Meaning |
+|---|---|
+| `--openapi <file>` | write an OpenAPI 3.1 document |
+| `--postman <file>` | write a Postman v2.1 collection |
+| `--url <base>` | base URL both documents advertise; defaults to the app's own `PORT` / `PUBLIC_DOMAIN` |
+
+Name at least one output. Commit what it writes: a generated document is
+an artifact a reviewer can diff, and an unexpected change in it usually
+means an unexpected change to the API.
+
+## Requirements
+
+`@tulipes/core` ≥ 0.6 · zod ≥ 3.25 (for the `zod/v4` subpath) — both peer
+dependencies, so this package never pins a second copy of either.
+
+---
+
+<div align="center">
+<sub>Part of <a href="https://www.npmjs.com/package/@tulipes/core">Tulipes</a></sub>
+</div>

package/dist/extract.d.ts

@@ -0,0 +1,41 @@
+import type { Ctx } from "@tulipes/core/boot";
+import type { ValidatableSchema } from "@tulipes/core/http";
+/**
+ * Everything a generated document needs about one endpoint, gathered from
+ * the running app rather than from parsing source — so a spec cannot
+ * describe a route that is not actually mounted, nor miss one that is.
+ */
+export interface SpecRoute {
+    id: string;
+    method: string;
+    /** As express declared it: `/users/:email`. */
+    path: string;
+    module: string;
+    /** Postman folder / OpenAPI tag. `info.folder`, else the module. */
+    folder: string;
+    name?: string;
+    description?: string;
+    params?: ValidatableSchema;
+    query?: ValidatableSchema;
+    body?: ValidatableSchema;
+    returns?: ValidatableSchema;
+    /** Roles that hold this permission. Empty means nobody can reach it. */
+    roles: string[];
+    /** Whether an unauthenticated caller can reach it. */
+    public: boolean;
+}
+export interface SpecSource {
+    app: {
+        name: string;
+        version?: string;
+    };
+    routes: SpecRoute[];
+    folders: string[];
+}
+export declare function extract(ctx: Ctx): SpecSource;
+/** `/users/:email` → `/users/{email}`, which is how OpenAPI writes params. */
+export declare function toOpenApiPath(path: string): string;
+/** `/users/:email` → `/users/{{email}}`, Postman's variable syntax. */
+export declare function toPostmanPath(path: string): string;
+/** The `:param` names a path declares, in order. */
+export declare function pathParams(path: string): string[];

package/dist/extract.js

@@ -0,0 +1,59 @@
+/** The role an unauthenticated caller has — see the framework's guest model. */
+const GUEST = "guest";
+export function extract(ctx) {
+    const grants = ctx.acl?.describe() ?? [];
+    // A grant reaches a permission directly, through its namespace wildcard,
+    // or through "*" — the same three ways the ACL itself resolves one, so
+    // the document can never disagree with what the app enforces.
+    const rolesFor = (id) => {
+        const namespace = `${id.split(":")[0]}:*`;
+        const roles = grants
+            .filter(({ resource }) => resource === id || resource === "*" || resource === namespace)
+            .map(({ role }) => role);
+        return [...new Set(roles)].sort();
+    };
+    const routes = [...ctx.routes.all()]
+        .map((record) => {
+        const { info } = record;
+        const roles = rolesFor(info.id);
+        return {
+            id: info.id,
+            method: record.method.toUpperCase(),
+            path: record.path,
+            module: record.module,
+            folder: info.folder ?? record.module,
+            ...(info.name && { name: info.name }),
+            ...(info.description && { description: info.description }),
+            ...(info.params && { params: info.params }),
+            ...(info.query && { query: info.query }),
+            ...(info.body && { body: info.body }),
+            ...(info.returns && { returns: info.returns }),
+            roles,
+            public: roles.includes(GUEST),
+        };
+    })
+        .sort((a, b) => a.folder.localeCompare(b.folder) || a.path.localeCompare(b.path));
+    return {
+        app: {
+            name: String(ctx.config.app?.name ?? "api"),
+            ...(typeof ctx.config.app?.version === "string" && {
+                version: String(ctx.config.app.version),
+            }),
+        },
+        routes,
+        folders: [...new Set(routes.map((route) => route.folder))].sort(),
+    };
+}
+/** `/users/:email` → `/users/{email}`, which is how OpenAPI writes params. */
+export function toOpenApiPath(path) {
+    return path.replace(/:(\w+)/g, "{$1}");
+}
+/** `/users/:email` → `/users/{{email}}`, Postman's variable syntax. */
+export function toPostmanPath(path) {
+    return path.replace(/:(\w+)/g, "{{$1}}");
+}
+/** The `:param` names a path declares, in order. */
+export function pathParams(path) {
+    return [...path.matchAll(/:(\w+)/g)].map((match) => match[1]);
+}
+//# sourceMappingURL=extract.js.map

package/dist/extract.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Generates an OpenAPI document and a Postman collection from a Tulipes
+ * app's declared routes.
+ *
+ * The source is the RAI registry of a *booted* app, not parsed source, so
+ * a generated document describes exactly what is mounted — it cannot
+ * invent an endpoint or miss one. `tulipes spec` is the CLI over this.
+ */
+export { extract, pathParams, toOpenApiPath, toPostmanPath } from "./extract.js";
+export type { SpecRoute, SpecSource } from "./extract.js";
+export { toOpenApi } from "./openapi.js";
+export type { GeneratedDocument, OpenApiOptions } from "./openapi.js";
+export { toPostman } from "./postman.js";
+export type { PostmanOptions } from "./postman.js";
+export { toJsonSchema, exampleFor } from "./json-schema.js";
+export type { JsonSchema } from "./json-schema.js";

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * Generates an OpenAPI document and a Postman collection from a Tulipes
+ * app's declared routes.
+ *
+ * The source is the RAI registry of a *booted* app, not parsed source, so
+ * a generated document describes exactly what is mounted — it cannot
+ * invent an endpoint or miss one. `tulipes spec` is the CLI over this.
+ */
+export { extract, pathParams, toOpenApiPath, toPostmanPath } from "./extract.js";
+export { toOpenApi } from "./openapi.js";
+export { toPostman } from "./postman.js";
+export { toJsonSchema, exampleFor } from "./json-schema.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEjF,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/json-schema.d.ts

@@ -0,0 +1,17 @@
+import type { ValidatableSchema } from "@tulipes/core/http";
+export type JsonSchema = Record<string, unknown>;
+export interface ConvertResult {
+    schema?: JsonSchema;
+    /** Why a schema was declared but produced nothing, for the report. */
+    warning?: string;
+}
+export declare function toJsonSchema(schema: ValidatableSchema | undefined, label: string): Promise<ConvertResult>;
+/**
+ * A best-effort example object, so a Postman request arrives with a body
+ * worth sending rather than an empty `{}`.
+ *
+ * Deliberately shallow and unclever: it reads defaults, examples, enums
+ * and types, and gives up on anything else. A wrong guess in a template
+ * body costs nothing; a wrong guess in the schema itself would.
+ */
+export declare function exampleFor(schema: JsonSchema | undefined): unknown;

package/dist/json-schema.js

@@ -0,0 +1,95 @@
+let converter;
+async function loadConverter() {
+    if (converter !== undefined)
+        return converter;
+    try {
+        const zod = (await import("zod/v4"));
+        converter = zod.toJSONSchema ?? null;
+    }
+    catch {
+        converter = null;
+    }
+    return converter;
+}
+export async function toJsonSchema(schema, label) {
+    if (!schema)
+        return {};
+    const convert = await loadConverter();
+    if (!convert) {
+        return { warning: `${label}: zod 4 not available, shape omitted` };
+    }
+    try {
+        const json = convert(schema, {
+            // A spec describes what a client sends and receives, so a schema
+            // that cannot be represented should degrade to "any" rather than
+            // abort the whole document.
+            unrepresentable: "any",
+            io: "input",
+        });
+        // The $schema declaration belongs to a standalone document, not to an
+        // inlined sub-schema inside OpenAPI or Postman.
+        delete json.$schema;
+        return { schema: json };
+    }
+    catch (error) {
+        return { warning: `${label}: ${error.message}` };
+    }
+}
+/**
+ * A best-effort example object, so a Postman request arrives with a body
+ * worth sending rather than an empty `{}`.
+ *
+ * Deliberately shallow and unclever: it reads defaults, examples, enums
+ * and types, and gives up on anything else. A wrong guess in a template
+ * body costs nothing; a wrong guess in the schema itself would.
+ */
+export function exampleFor(schema) {
+    if (!schema)
+        return undefined;
+    if (schema.default !== undefined)
+        return schema.default;
+    if (Array.isArray(schema.examples) && schema.examples.length > 0)
+        return schema.examples[0];
+    if (Array.isArray(schema.enum) && schema.enum.length > 0)
+        return schema.enum[0];
+    switch (schema.type) {
+        case "object": {
+            const properties = (schema.properties ?? {});
+            const out = {};
+            for (const [key, value] of Object.entries(properties))
+                out[key] = exampleFor(value);
+            return out;
+        }
+        case "array":
+            return [exampleFor(schema.items)].filter((value) => value !== undefined);
+        case "integer":
+        case "number":
+            return typeof schema.minimum === "number" ? schema.minimum : 0;
+        case "boolean":
+            return false;
+        case "null":
+            return null;
+        case "string":
+            return placeholderFor(schema);
+        default:
+            return null;
+    }
+}
+function placeholderFor(schema) {
+    switch (schema.format) {
+        case "email":
+            return "user@example.com";
+        case "uri":
+        case "url":
+            return "https://example.com";
+        case "uuid":
+            return "00000000-0000-0000-0000-000000000000";
+        case "date-time":
+            return new Date(0).toISOString();
+        case "date":
+            return "1970-01-01";
+        default:
+            return "string";
+    }
+}
+//# sourceMappingURL=json-schema.js.map

package/dist/json-schema.js.map

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

package/dist/openapi.d.ts

@@ -0,0 +1,18 @@
+import type { SpecSource } from "./extract.js";
+/**
+ * OpenAPI 3.1 — chosen over 3.0 because its schema dialect *is* JSON
+ * Schema 2020-12, which is exactly what zod emits. On 3.0 every schema
+ * would need lossy rewriting (nullable, exclusiveMinimum, examples), and
+ * a document that quietly misdescribes a type is worse than none.
+ */
+export interface OpenApiOptions {
+    /** Server URLs the document advertises. */
+    servers?: string[];
+    title?: string;
+    version?: string;
+}
+export interface GeneratedDocument {
+    document: Record<string, unknown>;
+    warnings: string[];
+}
+export declare function toOpenApi(source: SpecSource, options?: OpenApiOptions): Promise<GeneratedDocument>;

package/dist/openapi.js

@@ -0,0 +1,171 @@
+import { pathParams, toOpenApiPath } from "./extract.js";
+import { toJsonSchema } from "./json-schema.js";
+export async function toOpenApi(source, options = {}) {
+    const warnings = [];
+    const paths = {};
+    for (const route of source.routes) {
+        const path = toOpenApiPath(route.path);
+        paths[path] ??= {};
+        paths[path][route.method.toLowerCase()] = await operation(route, warnings);
+    }
+    return {
+        document: {
+            openapi: "3.1.0",
+            info: {
+                title: options.title ?? source.app.name,
+                version: options.version ?? source.app.version ?? "0.0.0",
+            },
+            ...(options.servers?.length && {
+                servers: options.servers.map((url) => ({ url })),
+            }),
+            tags: source.folders.map((name) => ({ name })),
+            paths,
+            components: {
+                securitySchemes: {
+                    bearerAuth: { type: "http", scheme: "bearer", bearerFormat: "JWT" },
+                },
+                schemas: { Envelope: ENVELOPE_SCHEMA, ApiError: API_ERROR_SCHEMA },
+            },
+        },
+        warnings,
+    };
+}
+async function operation(route, warnings) {
+    const collect = (warning) => {
+        if (warning)
+            warnings.push(warning);
+    };
+    const [params, query, body, returns] = await Promise.all([
+        toJsonSchema(route.params, `${route.id} params`),
+        toJsonSchema(route.query, `${route.id} query`),
+        toJsonSchema(route.body, `${route.id} body`),
+        toJsonSchema(route.returns, `${route.id} returns`),
+    ]);
+    [params, query, body, returns].forEach((result) => collect(result.warning));
+    const parameters = [
+        ...pathParameters(route, params.schema),
+        ...queryParameters(query.schema),
+    ];
+    return {
+        operationId: route.id,
+        tags: [route.folder],
+        ...(route.name && { summary: route.name }),
+        ...(route.description && { description: route.description }),
+        // The permission is the RAI id, and the roles holding it are policy a
+        // reader of the document genuinely needs.
+        "x-tulipes-permission": route.id,
+        "x-tulipes-roles": route.roles,
+        ...(parameters.length > 0 && { parameters }),
+        ...(body.schema && {
+            requestBody: {
+                required: true,
+                content: { "application/json": { schema: body.schema } },
+            },
+        }),
+        // A public route needs no credential; every other one does. An empty
+        // array on `security` is OpenAPI's way of saying "optional".
+        security: route.public ? [] : [{ bearerAuth: [] }],
+        responses: responses(route, returns.schema),
+    };
+}
+/**
+ * Path parameters are always required — a missing one does not match the
+ * route at all — and their shapes come from the `params` schema when the
+ * route declares one.
+ */
+function pathParameters(route, params) {
+    const properties = (params?.properties ?? {});
+    return pathParams(route.path).map((name) => ({
+        name,
+        in: "path",
+        required: true,
+        schema: properties[name] ?? { type: "string" },
+    }));
+}
+function queryParameters(query) {
+    if (!query?.properties)
+        return [];
+    const required = new Set(query.required ?? []);
+    return Object.entries(query.properties).map(([name, schema]) => ({
+        name,
+        in: "query",
+        required: required.has(name),
+        schema,
+    }));
+}
+/**
+ * Every response is the envelope, so the shell is described once and only
+ * `data` varies. A reader learns the contract from any single operation.
+ */
+function responses(route, returns) {
+    const success = {
+        description: "Success",
+        content: {
+            "application/json": {
+                schema: {
+                    allOf: [
+                        { $ref: "#/components/schemas/Envelope" },
+                        {
+                            type: "object",
+                            properties: {
+                                success: { const: true },
+                                data: returns ?? {},
+                            },
+                        },
+                    ],
+                },
+            },
+        },
+    };
+    const failure = (description) => ({
+        description,
+        content: {
+            "application/json": {
+                schema: {
+                    allOf: [
+                        { $ref: "#/components/schemas/Envelope" },
+                        { type: "object", properties: { success: { const: false }, data: { const: null } } },
+                    ],
+                },
+            },
+        },
+    });
+    return {
+        "200": success,
+        ...(hasValidation(route) && { "422": failure("Validation failed") }),
+        ...(!route.public && {
+            "401": failure("Authentication required"),
+            "403": failure("Authenticated, but not permitted"),
+        }),
+    };
+}
+const hasValidation = (route) => Boolean(route.params ?? route.query ?? route.body);
+const API_ERROR_SCHEMA = {
+    type: "object",
+    required: ["field", "message", "code"],
+    properties: {
+        field: { type: ["string", "null"], description: "The offending input, when there is one" },
+        message: { type: "string", description: "Translated into the caller's locale" },
+        code: { type: "string", description: "Stable and never translated — branch on this" },
+    },
+};
+const ENVELOPE_SCHEMA = {
+    type: "object",
+    required: ["success", "data", "errors", "meta"],
+    properties: {
+        success: { type: "boolean" },
+        data: { description: "The payload on success; null on failure" },
+        errors: { type: "array", items: { $ref: "#/components/schemas/ApiError" } },
+        meta: {
+            type: "object",
+            properties: {
+                action: { type: "string", description: "What the client should do next" },
+                page: { type: "integer" },
+                per_page: { type: "integer" },
+                total_pages: { type: "integer" },
+                total_items: { type: "integer" },
+            },
+        },
+    },
+};
+//# sourceMappingURL=openapi.js.map

package/dist/openapi.js.map

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

package/dist/postman.d.ts

@@ -0,0 +1,23 @@
+import type { SpecSource } from "./extract.js";
+import type { GeneratedDocument } from "./openapi.js";
+/**
+ * Postman Collection v2.1.
+ *
+ * This exists rather than telling people to import the OpenAPI document
+ * because a collection can carry what a spec cannot: folders per module,
+ * a `{{baseUrl}}` and `{{accessToken}}` wired through every request, and a
+ * login request that captures its own token so the rest of the collection
+ * is authenticated after one click.
+ */
+export interface PostmanOptions {
+    /** Default value for the collection's `baseUrl` variable. */
+    baseUrl?: string;
+    name?: string;
+    /**
+     * RAI id of the request that returns a token pair. Its response is
+     * captured into `{{accessToken}}`, so signing in once authenticates the
+     * whole collection. Defaults to "auth:login" when the app declares it.
+     */
+    loginRouteId?: string;
+}
+export declare function toPostman(source: SpecSource, options?: PostmanOptions): Promise<GeneratedDocument>;

package/dist/postman.js

@@ -0,0 +1,134 @@
+import { pathParams, toPostmanPath } from "./extract.js";
+import { exampleFor, toJsonSchema } from "./json-schema.js";
+export async function toPostman(source, options = {}) {
+    const warnings = [];
+    const loginId = resolveLoginId(source, options.loginRouteId);
+    // One folder per `folder` value — the module name unless a route said
+    // otherwise — so the collection mirrors how the app is organised.
+    const folders = await Promise.all(source.folders.map(async (folder) => ({
+        name: folder,
+        item: await Promise.all(source.routes
+            .filter((route) => route.folder === folder)
+            .map((route) => request(route, route.id === loginId, warnings))),
+    })));
+    return {
+        document: {
+            info: {
+                name: options.name ?? source.app.name,
+                description: "Generated from the app's declared routes. Sign in with the auth " +
+                    "request and every other request is authenticated automatically.",
+                schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
+            },
+            item: folders,
+            // Collection-level bearer auth, inherited by every request that does
+            // not override it — which is why public requests set auth: noauth.
+            auth: {
+                type: "bearer",
+                bearer: [{ key: "token", value: "{{accessToken}}", type: "string" }],
+            },
+            variable: [
+                { key: "baseUrl", value: options.baseUrl ?? "http://localhost:3000", type: "string" },
+                { key: "accessToken", value: "", type: "string" },
+                { key: "refreshToken", value: "", type: "string" },
+            ],
+        },
+        warnings,
+    };
+}
+/** Only use a login capture if the app actually declares that route. */
+function resolveLoginId(source, override) {
+    const candidate = override ?? "auth:login";
+    return source.routes.some((route) => route.id === candidate) ? candidate : undefined;
+}
+async function request(route, isLogin, warnings) {
+    const [query, body, params] = await Promise.all([
+        toJsonSchema(route.query, `${route.id} query`),
+        toJsonSchema(route.body, `${route.id} body`),
+        toJsonSchema(route.params, `${route.id} params`),
+    ]);
+    [query, body, params].forEach((r) => r.warning && warnings.push(r.warning));
+    const path = toPostmanPath(route.path).replace(/^\//, "").split("/");
+    return {
+        name: route.name ?? route.id,
+        request: {
+            method: route.method,
+            ...(route.description && { description: route.description }),
+            header: [
+                ...(body.schema ? [{ key: "Content-Type", value: "application/json" }] : []),
+                // Present but disabled: a reviewer can flip it on to check a
+                // locale without reading the i18n documentation first.
+                { key: "Accept-Language", value: "en", disabled: true },
+            ],
+            url: {
+                raw: `{{baseUrl}}/${path.join("/")}`,
+                host: ["{{baseUrl}}"],
+                path,
+                ...(queryItems(query.schema).length > 0 && { query: queryItems(query.schema) }),
+                ...(pathParams(route.path).length > 0 && {
+                    variable: pathVariables(route, params.schema),
+                }),
+            },
+            ...(body.schema && {
+                body: {
+                    mode: "raw",
+                    raw: JSON.stringify(exampleFor(body.schema), null, 2),
+                    options: { raw: { language: "json" } },
+                },
+            }),
+            // A public route must not send the collection's bearer token: it
+            // would mask the very thing a reviewer is checking.
+            ...(route.public && { auth: { type: "noauth" } }),
+        },
+        event: isLogin ? [captureTokens()] : [],
+    };
+}
+/** Query parameters are disabled by default, so a request runs as-is. */
+function queryItems(query) {
+    if (!query?.properties)
+        return [];
+    const required = new Set(query.required ?? []);
+    return Object.entries(query.properties).map(([key, schema]) => ({
+        key,
+        value: String(exampleFor(schema) ?? ""),
+        disabled: !required.has(key),
+        ...(typeof schema.description === "string" && { description: schema.description }),
+    }));
+}
+function pathVariables(route, params) {
+    const properties = (params?.properties ?? {});
+    return pathParams(route.path).map((key) => ({
+        key,
+        value: String(exampleFor(properties[key]) ?? ""),
+    }));
+}
+/**
+ * Captures the token pair out of the envelope. Written against
+ * `data.access_token`, which is the framework's shape — an app that
+ * renames them adjusts this one script rather than every request.
+ */
+function captureTokens() {
+    return {
+        listen: "test",
+        script: {
+            type: "text/javascript",
+            exec: [
+                "const body = pm.response.json();",
+                "if (body.success && body.data) {",
+                "  if (body.data.access_token) {",
+                "    pm.collectionVariables.set('accessToken', body.data.access_token);",
+                "  }",
+                "  if (body.data.refresh_token) {",
+                "    pm.collectionVariables.set('refreshToken', body.data.refresh_token);",
+                "  }",
+                "}",
+                "pm.test('enveloped response', () => {",
+                "  pm.expect(body).to.have.property('success');",
+                "  pm.expect(body).to.have.property('data');",
+                "  pm.expect(body).to.have.property('errors');",
+                "  pm.expect(body).to.have.property('meta');",
+                "});",
+            ],
+        },
+    };
+}
+//# sourceMappingURL=postman.js.map

package/dist/postman.js.map

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

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@tulipes/spec",
+  "version": "0.1.0",
+  "description": "Generate OpenAPI documents and Postman collections from a Tulipes app's declared routes",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.json",
+    "prepack": "yarn build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@tulipes/core": "^0.6.0",
+    "zod": "^3.25 || ^4"
+  },
+  "devDependencies": {
+    "@tulipes/core": "0.6.0",
+    "@types/node": "^24.2.0",
+    "typescript": "^7.0.2",
+    "zod": "^3.25"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kemora13conf/bp-backend-express.git",
+    "directory": "packages/spec"
+  },
+  "keywords": [
+    "tulipes",
+    "openapi",
+    "postman",
+    "api-documentation",
+    "express",
+    "zod"
+  ],
+  "license": "MIT"
+}