@geekmidas/constructs 10.0.0-alpha.11 → 10.0.0-alpha.13

package/dist/queue/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["obj: unknown","name: TName","handler: QueueHandler<TMessage, TServices, TLogger>","messageSchema: TMessage","timeout: number","services: TServices","logger: TLogger","batchSize?: number","fifo?: boolean","constructs: string[]","name: T","timeout: number","batchSize: number","constructs: T","services: T","logger: T","schema: T","fn: QueueHandler<NonNullable<TMessage>, TServices, TLogger>"],"sources":["../../src/queue/Queue.ts","../../src/queue/QueueBuilder.ts","../../src/queue/index.ts"],"sourcesContent":["import {\n\ttype EventPublisher,\n\ttype EventPublisherConnectionString,\n\ttype PublishableMessage,\n\tPublisher,\n} from '@geekmidas/events';\nimport type { Logger } from '@geekmidas/logger';\nimport { DEFAULT_LOGGER } from '@geekmidas/logger/console';\nimport {\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport type { InferStandardSchema } from '@geekmidas/schema';\nimport type { Service, ServiceRecord } from '@geekmidas/services';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport { Construct, ConstructType } from '../Construct';\n\n/**\n * The wire message a queue carries: `{ type: <queue name>, payload: <message> }`.\n * The producer publishes this shape and the worker receives the `payload`s as\n * its `messages`. Typing `type` to the queue name keeps the publisher fully\n * typed and lets pg-boss (local) / SQS (deployed) route by name.\n */\nexport type QueueMessage<\n\tTName extends string,\n\tTMessage extends StandardSchemaV1,\n> = PublishableMessage<TName, InferStandardSchema<TMessage>>;\n\n/**\n * A queue worker — a point-to-point SQS-style queue and its single consumer.\n * Unlike a `Subscriber` (topic fan-out, filtered by `subscribedEvents`), a queue\n * drains every message of its one `message` type. Build one with `q` (see\n * `QueueBuilder`); `gkm build` discovers it into the manifest's `queues` field.\n *\n * The producer side is {@link Queue.publisher} — a ready-to-inject `Service`\n * that any endpoint/function drops into `.services([...])` to send messages.\n */\nexport class Queue<\n\tTName extends string = string,\n\tTMessage extends StandardSchemaV1 = StandardSchemaV1,\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n> extends Construct<TLogger, string, undefined, undefined, TServices> {\n\t__IS_QUEUE__ = true;\n\n\tstatic isQueue(\n\t\tobj: unknown,\n\t): obj is Queue<string, StandardSchemaV1, Service[], Logger> {\n\t\treturn Boolean(\n\t\t\tobj &&\n\t\t\t\t(obj as { __IS_QUEUE__?: boolean }).__IS_QUEUE__ === true &&\n\t\t\t\t(obj as Construct).type === ConstructType.Queue,\n\t\t);\n\t}\n\n\t/**\n\t * The canonical id this queue is declared under.\n\t *\n\t * Derived from the name rather than given separately, so `emails` and\n\t * `Emails` are one queue. The name stays what it was: it is the wire `type`\n\t * a producer sends and the worker subscribes to, and changing that would\n\t * silently orphan in-flight messages.\n\t */\n\treadonly id: string;\n\n\t/**\n\t * The producer's env key. Read by both {@link declare} and\n\t * {@link publisher}, so what the target publishes and what the producer\n\t * looks up cannot drift.\n\t */\n\tprivate readonly connectionKey: string;\n\n\tconstructor(\n\t\tpublic readonly name: TName,\n\t\tpublic readonly handler: QueueHandler<TMessage, TServices, TLogger>,\n\t\tpublic readonly messageSchema: TMessage,\n\t\tpublic override readonly timeout: number = 30000,\n\t\tpublic override readonly services: TServices = [] as unknown as TServices,\n\t\tpublic override readonly logger: TLogger = DEFAULT_LOGGER as TLogger,\n\t\t/** SQS event-source batch size (deployed). */\n\t\tpublic readonly batchSize?: number,\n\t\t/** Whether the queue is FIFO (deployed). */\n\t\tpublic readonly fifo?: boolean,\n\t\t/**\n\t\t * The construct ids the *worker* `.dependsOn()` named — last, so no\n\t\t * existing positional argument moves.\n\t\t */\n\t\tconstructs: string[] = [],\n\t) {\n\t\tsuper(\n\t\t\tConstructType.Queue,\n\t\t\tlogger,\n\t\t\tservices,\n\t\t\t[],\n\t\t\tundefined,\n\t\t\tundefined,\n\t\t\ttimeout,\n\t\t\tundefined, // memorySize\n\t\t\tundefined, // auditorStorageService\n\t\t\tconstructs,\n\t\t);\n\n\t\tthis.id = canonicalId(name);\n\t\tthis.connectionKey = provideKey(this.id, 'publisherConnectionString');\n\t}\n\n\t/**\n\t * What this queue is in the manifest.\n\t *\n\t * A queue is a resource, not a handler: the worker is reached *through* it,\n\t * so the declaration carries the producer's key and nothing about the code\n\t * that drains it. The local target reads this to know which broker has to be\n\t * running and what connection string to inject.\n\t */\n\tdeclare(): Declaration[] {\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'queue',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.connectionKey],\n\t\t\t\t...(this.fifo ? { fifo: true } : {}),\n\t\t\t\t// Nested rather than a sibling node, because position carries the\n\t\t\t\t// trigger: this handler is reached by messages on this queue and\n\t\t\t\t// by nothing else, so there is no `trigger` field to keep in step.\n\t\t\t\t//\n\t\t\t\t// `handler` is the export name; which directory the build wrote it\n\t\t\t\t// to is the target's business, and a path with a cloud in it does\n\t\t\t\t// not belong in a neutral declaration.\n\t\t\t\tworker: {\n\t\t\t\t\tid: `${this.id}Worker`,\n\t\t\t\t\thandler: `${this.id}.handler`,\n\t\t\t\t\t// Filled by the build from what the worker declared. Empty is a\n\t\t\t\t\t// stated gap, not a claim that it reaches nothing.\n\t\t\t\t\tdependencies: [],\n\t\t\t\t},\n\t\t\t},\n\t\t];\n\t}\n\n\t/**\n\t * The producer side — a `Service` exposing an `EventPublisher` typed to this\n\t * queue's message. Inject it via `.services([queue.publisher])`; the handler\n\t * then calls `services.<name>Publisher.publish([{ type, payload }])`.\n\t *\n\t * It reads `<NAME>_PUBLISHER_CONNECTION_STRING` and builds the transport from\n\t * the URL protocol — `pgboss://` locally, `sqs://` deployed — so the same\n\t * code publishes to Postgres in dev and SQS in prod. Because it's a `Service`,\n\t * `Construct.getEnvironment()` sniffs it, so the env requirement flows into\n\t * the manifest and infra links exactly this queue with least privilege.\n\t */\n\t/**\n\t * The queue as a dependency — what `.dependsOn([emailsQueue])` dissolves\n\t * into, reachable as `services.emails`.\n\t *\n\t * It is the producer: a consumer is the worker written right here, so the\n\t * only thing another construct can want from a queue is the ability to send\n\t * to it. {@link publisher} is the same service under its older\n\t * `<name>Publisher` key, kept for `.services([queue.publisher])`.\n\t */\n\tget service(): Service<\n\t\tUncapitalize<TName>,\n\t\tEventPublisher<QueueMessage<TName, TMessage>>\n\t> {\n\t\tconst { register } = this.publisher;\n\n\t\treturn {\n\t\t\tserviceName: serviceKey(this.id) as Uncapitalize<TName>,\n\t\t\tregister,\n\t\t};\n\t}\n\n\tget publisher(): Service<\n\t\t`${TName}Publisher`,\n\t\tEventPublisher<QueueMessage<TName, TMessage>>\n\t> {\n\t\tconst envVar = this.connectionKey;\n\t\treturn {\n\t\t\tserviceName: `${this.name}Publisher`,\n\t\t\tasync register({ envParser }) {\n\t\t\t\tconst { connectionString } = envParser\n\t\t\t\t\t.create((get) => ({\n\t\t\t\t\t\tconnectionString: get(envVar).string(),\n\t\t\t\t\t}))\n\t\t\t\t\t.parse();\n\n\t\t\t\treturn Publisher.fromConnectionString<QueueMessage<TName, TMessage>>(\n\t\t\t\t\tconnectionString as EventPublisherConnectionString,\n\t\t\t\t);\n\t\t\t},\n\t\t};\n\t}\n}\n\n/** The context a queue handler receives — a batch of typed messages. */\nexport type QueueContext<\n\tTMessage extends StandardSchemaV1,\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n> = {\n\tmessages: InferStandardSchema<TMessage>[];\n\tservices: ServiceRecord<TServices>;\n\tlogger: TLogger;\n};\n\nexport type QueueHandler<\n\tTMessage extends StandardSchemaV1,\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n> = (\n\tctx: QueueContext<TMessage, TServices, TLogger>,\n) => unknown | Promise<unknown>;\n","import type { Logger } from '@geekmidas/logger';\nimport { DEFAULT_LOGGER } from '@geekmidas/logger/console';\nimport type { Service } from '@geekmidas/services';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport { cloneWith } from '../clone';\nimport {\n\ttype Consumable,\n\tidsOf,\n\ttype ServicesOf,\n\tservicesOf,\n} from '../construct-interface';\nimport { Queue, type QueueHandler } from './Queue';\n\n/**\n * Builds a {@link Queue} worker — `q.queue('orders').services([db]).message(schema).handle(fn)`.\n * Services are an array (sniffed for required env vars); `message` is the typed\n * job payload; `handle` is the single consumer. The queue name is captured as a\n * literal so `queue.publisher` is typed to `{ type: '<name>', payload }`.\n */\nexport class QueueBuilder<\n\tTName extends string = string,\n\tTMessage extends StandardSchemaV1 | undefined = undefined,\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n> {\n\tprivate _name?: string;\n\tprivate _messageSchema?: TMessage;\n\tprivate _timeout = 30000;\n\tprivate _batchSize?: number;\n\tprivate _fifo?: boolean;\n\tprivate _services: TServices = [] as Service[] as TServices;\n\t/** The construct ids `.dependsOn()` named — what the manifest records. */\n\tpublic _constructs: string[] = [];\n\tprivate _logger: TLogger = DEFAULT_LOGGER as TLogger;\n\n\t/** The queue name — drives the infra queue and its `<NAME>_*` env vars. */\n\tqueue<T extends string>(\n\t\tname: T,\n\t): QueueBuilder<T, TMessage, TServices, TLogger> {\n\t\treturn cloneWith(this, { _name: name }) as unknown as QueueBuilder<\n\t\t\tT,\n\t\t\tTMessage,\n\t\t\tTServices,\n\t\t\tTLogger\n\t\t>;\n\t}\n\n\ttimeout(timeout: number): this {\n\t\treturn cloneWith(this, { _timeout: timeout });\n\t}\n\n\t/** SQS event-source batch size (deployed). */\n\tbatchSize(batchSize: number): this {\n\t\treturn cloneWith(this, { _batchSize: batchSize });\n\t}\n\n\t/** Mark the queue as FIFO (deployed). */\n\tfifo(fifo = true): this {\n\t\treturn cloneWith(this, { _fifo: fifo });\n\t}\n\n\t/**\n\t * Depend on constructs — a database, a bucket, a mail sender, a queue, a\n\t * topic.\n\t *\n\t * It records the edge and dissolves each construct's client into the\n\t * handler's service record under the construct's own id, so\n\t * `.dependsOn([uploads])` is what makes `services.uploads` exist and type.\n\t *\n\t * Constructs only. A `Service` does not match the shape, which is what keeps\n\t * env sniffing confined to `.services()` and the explicit lift.\n\t */\n\tdependsOn<const T extends readonly Consumable[]>(\n\t\tconstructs: T,\n\t): QueueBuilder<TName, TMessage, [...TServices, ...ServicesOf<T>], TLogger> {\n\t\t// Both halves of the edge, from one call and one clone: the services the\n\t\t// handler runs with, and the ids the manifest records. Recording them\n\t\t// separately is what let them drift apart.\n\t\t//\n\t\t// `servicesOf` is the half that validates, so it runs first — recording\n\t\t// ids ahead of it left a caught `NotAConstruct` with `undefined` already\n\t\t// on a `string[]`.\n\t\tconst services = servicesOf(constructs) as unknown as Service[];\n\n\t\treturn cloneWith(this, {\n\t\t\t_services: [...this._services, ...services],\n\t\t\t_constructs: idsOf(constructs, this._constructs),\n\t\t}) as unknown as QueueBuilder<\n\t\t\tTName,\n\t\t\tTMessage,\n\t\t\t[...TServices, ...ServicesOf<T>],\n\t\t\tTLogger\n\t\t>;\n\t}\n\n\tservices<T extends Service[]>(\n\t\tservices: T,\n\t): QueueBuilder<TName, TMessage, [...TServices, ...T], TLogger> {\n\t\treturn cloneWith(this, {\n\t\t\t_services: [...this._services, ...services] as unknown as TServices,\n\t\t}) as unknown as QueueBuilder<\n\t\t\tTName,\n\t\t\tTMessage,\n\t\t\t[...TServices, ...T],\n\t\t\tTLogger\n\t\t>;\n\t}\n\n\tlogger<T extends Logger>(\n\t\tlogger: T,\n\t): QueueBuilder<TName, TMessage, TServices, T> {\n\t\treturn cloneWith(this, {\n\t\t\t_logger: logger as unknown as TLogger,\n\t\t}) as unknown as QueueBuilder<TName, TMessage, TServices, T>;\n\t}\n\n\t/** The typed message (job) payload the queue carries. */\n\tmessage<T extends StandardSchemaV1>(\n\t\tschema: T,\n\t): QueueBuilder<TName, T, TServices, TLogger> {\n\t\treturn cloneWith(this, {\n\t\t\t_messageSchema: schema as unknown as TMessage,\n\t\t}) as unknown as QueueBuilder<TName, T, TServices, TLogger>;\n\t}\n\n\thandle(\n\t\tfn: QueueHandler<NonNullable<TMessage>, TServices, TLogger>,\n\t): Queue<TName, NonNullable<TMessage>, TServices, TLogger> {\n\t\tif (!this._name) {\n\t\t\tthrow new Error(\n\t\t\t\t'Queue requires a name — call .queue(name) before .handle().',\n\t\t\t);\n\t\t}\n\t\tif (!this._messageSchema) {\n\t\t\tthrow new Error(\n\t\t\t\t'Queue requires a message schema — call .message(schema) before .handle().',\n\t\t\t);\n\t\t}\n\n\t\tconst queue = new Queue<TName, NonNullable<TMessage>, TServices, TLogger>(\n\t\t\tthis._name as TName,\n\t\t\tfn,\n\t\t\tthis._messageSchema as NonNullable<TMessage>,\n\t\t\tthis._timeout,\n\t\t\tthis._services,\n\t\t\tthis._logger,\n\t\t\tthis._batchSize,\n\t\t\tthis._fifo,\n\t\t\tthis._constructs,\n\t\t);\n\n\t\t// No reset. `.handle()` reads this builder and leaves it alone, so a\n\t\t// configured base — `const fn = f.logger(log).timeout(60_000)` — keeps\n\t\t// its configuration for every construct built from it. The reset that\n\t\t// used to be here wiped the base on first use, which made a base usable\n\t\t// exactly once, and quietly reverted the logger to the default.\n\n\t\treturn queue;\n\t}\n}\n","export {\n\tQueue,\n\ttype QueueContext,\n\ttype QueueHandler,\n\ttype QueueMessage,\n} from './Queue';\n\nimport { QueueBuilder } from './QueueBuilder';\n\nexport { QueueBuilder } from './QueueBuilder';\n\nexport const q = new QueueBuilder();\n"],"mappings":";;;;;;;;;;;;;;;;;AAuCA,IAAa,QAAb,cAKU,UAA4D;CACrE,eAAe;CAEf,OAAO,QACNA,KAC4D;AAC5D,SAAO,QACN,OACE,IAAmC,iBAAiB,QACpD,IAAkB,SAAS,cAAc,MAC3C;CACD;;;;;;;;;CAUD,AAAS;;;;;;CAOT,AAAiB;CAEjB,YACiBC,MACAC,SACAC,eACSC,UAAkB,KAClBC,WAAsB,CAAE,GACxBC,SAAkB,gBAE3BC,WAEAC,MAKhBC,aAAuB,CAAE,GACxB;AACD,QACC,cAAc,OACd,QACA,UACA,CAAE,mBAGF,yBAGA,WACA;EA3Be;EACA;EACA;EACS;EACA;EACA;EAET;EAEA;AAoBhB,OAAK,KAAK,YAAY,KAAK;AAC3B,OAAK,gBAAgB,WAAW,KAAK,IAAI,4BAA4B;CACrE;;;;;;;;;CAUD,UAAyB;AACxB,SAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,UAAU,CAAC,KAAK,aAAc;GAC9B,GAAI,KAAK,OAAO,EAAE,MAAM,KAAM,IAAG,CAAE;GAQnC,QAAQ;IACP,KAAK,EAAE,KAAK,GAAG;IACf,UAAU,EAAE,KAAK,GAAG;IAGpB,cAAc,CAAE;GAChB;EACD,CACD;CACD;;;;;;;;;;;;;;;;;;;;;CAsBD,IAAI,UAGF;EACD,MAAM,EAAE,UAAU,GAAG,KAAK;AAE1B,SAAO;GACN,aAAa,WAAW,KAAK,GAAG;GAChC;EACA;CACD;CAED,IAAI,YAGF;EACD,MAAM,SAAS,KAAK;AACpB,SAAO;GACN,cAAc,EAAE,KAAK,KAAK;GAC1B,MAAM,SAAS,EAAE,WAAW,EAAE;IAC7B,MAAM,EAAE,kBAAkB,GAAG,UAC3B,OAAO,CAAC,SAAS,EACjB,kBAAkB,IAAI,OAAO,CAAC,QAAQ,CACtC,GAAE,CACF,OAAO;AAET,WAAO,UAAU,qBAChB,iBACA;GACD;EACD;CACD;AACD;;;;;;;;;;AC9KD,IAAa,eAAb,MAKE;CACD,AAAQ;CACR,AAAQ;CACR,AAAQ,WAAW;CACnB,AAAQ;CACR,AAAQ;CACR,AAAQ,YAAuB,CAAE;;CAEjC,AAAO,cAAwB,CAAE;CACjC,AAAQ,UAAmB;;CAG3B,MACCC,MACgD;AAChD,SAAO,UAAU,MAAM,EAAE,OAAO,KAAM,EAAC;CAMvC;CAED,QAAQC,SAAuB;AAC9B,SAAO,UAAU,MAAM,EAAE,UAAU,QAAS,EAAC;CAC7C;;CAGD,UAAUC,WAAyB;AAClC,SAAO,UAAU,MAAM,EAAE,YAAY,UAAW,EAAC;CACjD;;CAGD,KAAK,OAAO,MAAY;AACvB,SAAO,UAAU,MAAM,EAAE,OAAO,KAAM,EAAC;CACvC;;;;;;;;;;;;CAaD,UACCC,YAC2E;EAQ3E,MAAM,WAAW,WAAW,WAAW;AAEvC,SAAO,UAAU,MAAM;GACtB,WAAW,CAAC,GAAG,KAAK,WAAW,GAAG,QAAS;GAC3C,aAAa,MAAM,YAAY,KAAK,YAAY;EAChD,EAAC;CAMF;CAED,SACCC,UAC+D;AAC/D,SAAO,UAAU,MAAM,EACtB,WAAW,CAAC,GAAG,KAAK,WAAW,GAAG,QAAS,EAC3C,EAAC;CAMF;CAED,OACCC,QAC8C;AAC9C,SAAO,UAAU,MAAM,EACtB,SAAS,OACT,EAAC;CACF;;CAGD,QACCC,QAC6C;AAC7C,SAAO,UAAU,MAAM,EACtB,gBAAgB,OAChB,EAAC;CACF;CAED,OACCC,IAC0D;AAC1D,OAAK,KAAK,MACT,OAAM,IAAI,MACT;AAGF,OAAK,KAAK,eACT,OAAM,IAAI,MACT;EAIF,MAAM,QAAQ,IAAI,MACjB,KAAK,OACL,IACA,KAAK,gBACL,KAAK,UACL,KAAK,WACL,KAAK,SACL,KAAK,YACL,KAAK,OACL,KAAK;AASN,SAAO;CACP;AACD;;;;ACpJD,MAAa,IAAI,IAAI"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/queue/Queue.ts","../../src/queue/QueueBuilder.ts","../../src/queue/index.ts"],"sourcesContent":["import {\n\ttype EventPublisher,\n\ttype EventPublisherConnectionString,\n\ttype PublishableMessage,\n\tPublisher,\n} from '@geekmidas/events';\nimport type { Logger } from '@geekmidas/logger';\nimport { DEFAULT_LOGGER } from '@geekmidas/logger/console';\nimport {\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport type { InferStandardSchema } from '@geekmidas/schema';\nimport type { Service, ServiceRecord } from '@geekmidas/services';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport { Construct, ConstructType } from '../Construct';\n\n/**\n * The wire message a queue carries: `{ type: <queue name>, payload: <message> }`.\n * The producer publishes this shape and the worker receives the `payload`s as\n * its `messages`. Typing `type` to the queue name keeps the publisher fully\n * typed and lets pg-boss (local) / SQS (deployed) route by name.\n */\nexport type QueueMessage<\n\tTName extends string,\n\tTMessage extends StandardSchemaV1,\n> = PublishableMessage<TName, InferStandardSchema<TMessage>>;\n\n/**\n * A queue worker — a point-to-point SQS-style queue and its single consumer.\n * Unlike a `Subscriber` (topic fan-out, filtered by `subscribedEvents`), a queue\n * drains every message of its one `message` type. Build one with `q` (see\n * `QueueBuilder`); `gkm build` discovers it into the manifest's `queues` field.\n *\n * The producer side is {@link Queue.publisher} — a ready-to-inject `Service`\n * that any endpoint/function drops into `.services([...])` to send messages.\n */\nexport class Queue<\n\tTName extends string = string,\n\tTMessage extends StandardSchemaV1 = StandardSchemaV1,\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n> extends Construct<TLogger, string, undefined, undefined, TServices> {\n\t__IS_QUEUE__ = true;\n\n\tstatic isQueue(\n\t\tobj: unknown,\n\t): obj is Queue<string, StandardSchemaV1, Service[], Logger> {\n\t\treturn Boolean(\n\t\t\tobj &&\n\t\t\t\t(obj as { __IS_QUEUE__?: boolean }).__IS_QUEUE__ === true &&\n\t\t\t\t(obj as Construct).type === ConstructType.Queue,\n\t\t);\n\t}\n\n\t/**\n\t * The canonical id this queue is declared under.\n\t *\n\t * Derived from the name rather than given separately, so `emails` and\n\t * `Emails` are one queue. The name stays what it was: it is the wire `type`\n\t * a producer sends and the worker subscribes to, and changing that would\n\t * silently orphan in-flight messages.\n\t */\n\treadonly id: string;\n\n\t/**\n\t * The producer's env key. Read by both {@link declare} and\n\t * {@link publisher}, so what the target publishes and what the producer\n\t * looks up cannot drift.\n\t */\n\tprivate readonly connectionKey: string;\n\n\tconstructor(\n\t\tpublic readonly name: TName,\n\t\tpublic readonly handler: QueueHandler<TMessage, TServices, TLogger>,\n\t\tpublic readonly messageSchema: TMessage,\n\t\tpublic override readonly timeout: number = 30000,\n\t\tpublic override readonly services: TServices = [] as unknown as TServices,\n\t\tpublic override readonly logger: TLogger = DEFAULT_LOGGER as TLogger,\n\t\t/** SQS event-source batch size (deployed). */\n\t\tpublic readonly batchSize?: number,\n\t\t/** Whether the queue is FIFO (deployed). */\n\t\tpublic readonly fifo?: boolean,\n\t\t/**\n\t\t * The construct ids the *worker* `.dependsOn()` named — last, so no\n\t\t * existing positional argument moves.\n\t\t */\n\t\tconstructs: string[] = [],\n\t) {\n\t\tsuper(\n\t\t\tConstructType.Queue,\n\t\t\tlogger,\n\t\t\tservices,\n\t\t\t[],\n\t\t\tundefined,\n\t\t\tundefined,\n\t\t\ttimeout,\n\t\t\tundefined, // memorySize\n\t\t\tundefined, // auditorStorageService\n\t\t\tconstructs,\n\t\t);\n\n\t\tthis.id = canonicalId(name);\n\t\tthis.connectionKey = provideKey(this.id, 'publisherConnectionString');\n\t}\n\n\t/**\n\t * What this queue is in the manifest.\n\t *\n\t * A queue is a resource, not a handler: the worker is reached *through* it,\n\t * so the declaration carries the producer's key and nothing about the code\n\t * that drains it. The local target reads this to know which broker has to be\n\t * running and what connection string to inject.\n\t */\n\tdeclare(): Declaration[] {\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'queue',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.connectionKey],\n\t\t\t\t...(this.fifo ? { fifo: true } : {}),\n\t\t\t\t// Nested rather than a sibling node, because position carries the\n\t\t\t\t// trigger: this handler is reached by messages on this queue and\n\t\t\t\t// by nothing else, so there is no `trigger` field to keep in step.\n\t\t\t\t//\n\t\t\t\t// `handler` is the export name; which directory the build wrote it\n\t\t\t\t// to is the target's business, and a path with a cloud in it does\n\t\t\t\t// not belong in a neutral declaration.\n\t\t\t\tworker: {\n\t\t\t\t\tid: `${this.id}Worker`,\n\t\t\t\t\thandler: `${this.id}.handler`,\n\t\t\t\t\t// Filled by the build from what the worker declared. Empty is a\n\t\t\t\t\t// stated gap, not a claim that it reaches nothing.\n\t\t\t\t\tdependencies: [],\n\t\t\t\t},\n\t\t\t},\n\t\t];\n\t}\n\n\t/**\n\t * The producer side — a `Service` exposing an `EventPublisher` typed to this\n\t * queue's message. Inject it via `.services([queue.publisher])`; the handler\n\t * then calls `services.<name>Publisher.publish([{ type, payload }])`.\n\t *\n\t * It reads `<NAME>_PUBLISHER_CONNECTION_STRING` and builds the transport from\n\t * the URL protocol — `pgboss://` locally, `sqs://` deployed — so the same\n\t * code publishes to Postgres in dev and SQS in prod. Because it's a `Service`,\n\t * `Construct.getEnvironment()` sniffs it, so the env requirement flows into\n\t * the manifest and infra links exactly this queue with least privilege.\n\t */\n\t/**\n\t * The queue as a dependency — what `.dependsOn([emailsQueue])` dissolves\n\t * into, reachable as `services.emails`.\n\t *\n\t * It is the producer: a consumer is the worker written right here, so the\n\t * only thing another construct can want from a queue is the ability to send\n\t * to it. {@link publisher} is the same service under its older\n\t * `<name>Publisher` key, kept for `.services([queue.publisher])`.\n\t */\n\tget service(): Service<\n\t\tUncapitalize<TName>,\n\t\tEventPublisher<QueueMessage<TName, TMessage>>\n\t> {\n\t\tconst { register } = this.publisher;\n\n\t\treturn {\n\t\t\tserviceName: serviceKey(this.id) as Uncapitalize<TName>,\n\t\t\tregister,\n\t\t};\n\t}\n\n\tget publisher(): Service<\n\t\t`${TName}Publisher`,\n\t\tEventPublisher<QueueMessage<TName, TMessage>>\n\t> {\n\t\tconst envVar = this.connectionKey;\n\t\treturn {\n\t\t\tserviceName: `${this.name}Publisher`,\n\t\t\tasync register({ envParser }) {\n\t\t\t\tconst { connectionString } = envParser\n\t\t\t\t\t.create((get) => ({\n\t\t\t\t\t\tconnectionString: get(envVar).string(),\n\t\t\t\t\t}))\n\t\t\t\t\t.parse();\n\n\t\t\t\treturn Publisher.fromConnectionString<QueueMessage<TName, TMessage>>(\n\t\t\t\t\tconnectionString as EventPublisherConnectionString,\n\t\t\t\t);\n\t\t\t},\n\t\t};\n\t}\n}\n\n/** The context a queue handler receives — a batch of typed messages. */\nexport type QueueContext<\n\tTMessage extends StandardSchemaV1,\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n> = {\n\tmessages: InferStandardSchema<TMessage>[];\n\tservices: ServiceRecord<TServices>;\n\tlogger: TLogger;\n};\n\nexport type QueueHandler<\n\tTMessage extends StandardSchemaV1,\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n> = (\n\tctx: QueueContext<TMessage, TServices, TLogger>,\n) => unknown | Promise<unknown>;\n","import type { Logger } from '@geekmidas/logger';\nimport { DEFAULT_LOGGER } from '@geekmidas/logger/console';\nimport type { Service } from '@geekmidas/services';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport { cloneWith } from '../clone';\nimport {\n\ttype Consumable,\n\tidsOf,\n\ttype ServicesOf,\n\tservicesOf,\n} from '../construct-interface';\nimport { Queue, type QueueHandler } from './Queue';\n\n/**\n * Builds a {@link Queue} worker — `q.queue('orders').services([db]).message(schema).handle(fn)`.\n * Services are an array (sniffed for required env vars); `message` is the typed\n * job payload; `handle` is the single consumer. The queue name is captured as a\n * literal so `queue.publisher` is typed to `{ type: '<name>', payload }`.\n */\nexport class QueueBuilder<\n\tTName extends string = string,\n\tTMessage extends StandardSchemaV1 | undefined = undefined,\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n> {\n\tprivate _name?: string;\n\tprivate _messageSchema?: TMessage;\n\tprivate _timeout = 30000;\n\tprivate _batchSize?: number;\n\tprivate _fifo?: boolean;\n\tprivate _services: TServices = [] as Service[] as TServices;\n\t/** The construct ids `.dependsOn()` named — what the manifest records. */\n\tpublic _constructs: string[] = [];\n\tprivate _logger: TLogger = DEFAULT_LOGGER as TLogger;\n\n\t/** The queue name — drives the infra queue and its `<NAME>_*` env vars. */\n\tqueue<T extends string>(\n\t\tname: T,\n\t): QueueBuilder<T, TMessage, TServices, TLogger> {\n\t\treturn cloneWith(this, { _name: name }) as unknown as QueueBuilder<\n\t\t\tT,\n\t\t\tTMessage,\n\t\t\tTServices,\n\t\t\tTLogger\n\t\t>;\n\t}\n\n\ttimeout(timeout: number): this {\n\t\treturn cloneWith(this, { _timeout: timeout });\n\t}\n\n\t/** SQS event-source batch size (deployed). */\n\tbatchSize(batchSize: number): this {\n\t\treturn cloneWith(this, { _batchSize: batchSize });\n\t}\n\n\t/** Mark the queue as FIFO (deployed). */\n\tfifo(fifo = true): this {\n\t\treturn cloneWith(this, { _fifo: fifo });\n\t}\n\n\t/**\n\t * Depend on constructs — a database, a bucket, a mail sender, a queue, a\n\t * topic.\n\t *\n\t * It records the edge and dissolves each construct's client into the\n\t * handler's service record under the construct's own id, so\n\t * `.dependsOn([uploads])` is what makes `services.uploads` exist and type.\n\t *\n\t * Constructs only. A `Service` does not match the shape, which is what keeps\n\t * env sniffing confined to `.services()` and the explicit lift.\n\t */\n\tdependsOn<const T extends readonly Consumable[]>(\n\t\tconstructs: T,\n\t): QueueBuilder<TName, TMessage, [...TServices, ...ServicesOf<T>], TLogger> {\n\t\t// Both halves of the edge, from one call and one clone: the services the\n\t\t// handler runs with, and the ids the manifest records. Recording them\n\t\t// separately is what let them drift apart.\n\t\t//\n\t\t// `servicesOf` is the half that validates, so it runs first — recording\n\t\t// ids ahead of it left a caught `NotAConstruct` with `undefined` already\n\t\t// on a `string[]`.\n\t\tconst services = servicesOf(constructs) as unknown as Service[];\n\n\t\treturn cloneWith(this, {\n\t\t\t_services: [...this._services, ...services],\n\t\t\t_constructs: idsOf(constructs, this._constructs),\n\t\t}) as unknown as QueueBuilder<\n\t\t\tTName,\n\t\t\tTMessage,\n\t\t\t[...TServices, ...ServicesOf<T>],\n\t\t\tTLogger\n\t\t>;\n\t}\n\n\tservices<T extends Service[]>(\n\t\tservices: T,\n\t): QueueBuilder<TName, TMessage, [...TServices, ...T], TLogger> {\n\t\treturn cloneWith(this, {\n\t\t\t_services: [...this._services, ...services] as unknown as TServices,\n\t\t}) as unknown as QueueBuilder<\n\t\t\tTName,\n\t\t\tTMessage,\n\t\t\t[...TServices, ...T],\n\t\t\tTLogger\n\t\t>;\n\t}\n\n\tlogger<T extends Logger>(\n\t\tlogger: T,\n\t): QueueBuilder<TName, TMessage, TServices, T> {\n\t\treturn cloneWith(this, {\n\t\t\t_logger: logger as unknown as TLogger,\n\t\t}) as unknown as QueueBuilder<TName, TMessage, TServices, T>;\n\t}\n\n\t/** The typed message (job) payload the queue carries. */\n\tmessage<T extends StandardSchemaV1>(\n\t\tschema: T,\n\t): QueueBuilder<TName, T, TServices, TLogger> {\n\t\treturn cloneWith(this, {\n\t\t\t_messageSchema: schema as unknown as TMessage,\n\t\t}) as unknown as QueueBuilder<TName, T, TServices, TLogger>;\n\t}\n\n\thandle(\n\t\tfn: QueueHandler<NonNullable<TMessage>, TServices, TLogger>,\n\t): Queue<TName, NonNullable<TMessage>, TServices, TLogger> {\n\t\tif (!this._name) {\n\t\t\tthrow new Error(\n\t\t\t\t'Queue requires a name — call .queue(name) before .handle().',\n\t\t\t);\n\t\t}\n\t\tif (!this._messageSchema) {\n\t\t\tthrow new Error(\n\t\t\t\t'Queue requires a message schema — call .message(schema) before .handle().',\n\t\t\t);\n\t\t}\n\n\t\tconst queue = new Queue<TName, NonNullable<TMessage>, TServices, TLogger>(\n\t\t\tthis._name as TName,\n\t\t\tfn,\n\t\t\tthis._messageSchema as NonNullable<TMessage>,\n\t\t\tthis._timeout,\n\t\t\tthis._services,\n\t\t\tthis._logger,\n\t\t\tthis._batchSize,\n\t\t\tthis._fifo,\n\t\t\tthis._constructs,\n\t\t);\n\n\t\t// No reset. `.handle()` reads this builder and leaves it alone, so a\n\t\t// configured base — `const fn = f.logger(log).timeout(60_000)` — keeps\n\t\t// its configuration for every construct built from it. The reset that\n\t\t// used to be here wiped the base on first use, which made a base usable\n\t\t// exactly once, and quietly reverted the logger to the default.\n\n\t\treturn queue;\n\t}\n}\n","export {\n\tQueue,\n\ttype QueueContext,\n\ttype QueueHandler,\n\ttype QueueMessage,\n} from './Queue';\n\nimport { QueueBuilder } from './QueueBuilder';\n\nexport { QueueBuilder } from './QueueBuilder';\n\nexport const q = new QueueBuilder();\n"],"mappings":";;;;;;;;;;;;;;;;AAuCA,IAAa,QAAb,cAKU,UAA4D;CA+BpD;CACA;CACA;CACS;CACA;CACA;CAET;CAEA;CAvCjB,eAAe;CAEf,OAAO,QACN,KAC4D;EAC5D,OAAO,QACN,OACE,IAAmC,iBAAiB,QACpD,IAAkB,SAAA,8BACrB;CACD;;;;;;;;;CAUA;;;;;;CAOA;CAEA,YACC,MACA,SACA,eACA,UAA2C,KAC3C,WAA+C,CAAC,GAChD,SAA2C,gBAE3C,WAEA,MAKA,aAAuB,CAAC,GACvB;EACD,MAAA,gCAEC,QACA,UACA,CAAC,GACD,KAAA,GACA,KAAA,GACA,SACA,KAAA,GACA,KAAA,GACA,UACD;EA3BgB,KAAA,OAAA;EACA,KAAA,UAAA;EACA,KAAA,gBAAA;EACS,KAAA,UAAA;EACA,KAAA,WAAA;EACA,KAAA,SAAA;EAET,KAAA,YAAA;EAEA,KAAA,OAAA;EAoBhB,KAAK,KAAK,YAAY,IAAI;EAC1B,KAAK,gBAAgB,WAAW,KAAK,IAAI,2BAA2B;CACrE;;;;;;;;;CAUA,UAAyB;EACxB,OAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,UAAU,CAAC,KAAK,aAAa;GAC7B,GAAI,KAAK,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;GAQlC,QAAQ;IACP,IAAI,GAAG,KAAK,GAAG;IACf,SAAS,GAAG,KAAK,GAAG;IAGpB,cAAc,CAAC;GAChB;EACD,CACD;CACD;;;;;;;;;;;;;;;;;;;;;CAsBA,IAAI,UAGF;EACD,MAAM,EAAE,aAAa,KAAK;EAE1B,OAAO;GACN,aAAa,WAAW,KAAK,EAAE;GAC/B;EACD;CACD;CAEA,IAAI,YAGF;EACD,MAAM,SAAS,KAAK;EACpB,OAAO;GACN,aAAa,GAAG,KAAK,KAAK;GAC1B,MAAM,SAAS,EAAE,aAAa;IAC7B,MAAM,EAAE,qBAAqB,UAC3B,QAAQ,SAAS,EACjB,kBAAkB,IAAI,MAAM,CAAC,CAAC,OAAO,EACtC,EAAE,CAAC,CACF,MAAM;IAER,OAAO,UAAU,qBAChB,gBACD;GACD;EACD;CACD;AACD;;;;;;;;;AC9KA,IAAa,eAAb,MAKE;CACD;CACA;CACA,WAAmB;CACnB;CACA;CACA,YAA+B,CAAC;;CAEhC,cAA+B,CAAC;CAChC,UAA2B;;CAG3B,MACC,MACgD;EAChD,OAAO,UAAU,MAAM,EAAE,OAAO,KAAK,CAAC;CAMvC;CAEA,QAAQ,SAAuB;EAC9B,OAAO,UAAU,MAAM,EAAE,UAAU,QAAQ,CAAC;CAC7C;;CAGA,UAAU,WAAyB;EAClC,OAAO,UAAU,MAAM,EAAE,YAAY,UAAU,CAAC;CACjD;;CAGA,KAAK,OAAO,MAAY;EACvB,OAAO,UAAU,MAAM,EAAE,OAAO,KAAK,CAAC;CACvC;;;;;;;;;;;;CAaA,UACC,YAC2E;EAQ3E,MAAM,WAAW,WAAW,UAAU;EAEtC,OAAO,UAAU,MAAM;GACtB,WAAW,CAAC,GAAG,KAAK,WAAW,GAAG,QAAQ;GAC1C,aAAa,MAAM,YAAY,KAAK,WAAW;EAChD,CAAC;CAMF;CAEA,SACC,UAC+D;EAC/D,OAAO,UAAU,MAAM,EACtB,WAAW,CAAC,GAAG,KAAK,WAAW,GAAG,QAAQ,EAC3C,CAAC;CAMF;CAEA,OACC,QAC8C;EAC9C,OAAO,UAAU,MAAM,EACtB,SAAS,OACV,CAAC;CACF;;CAGA,QACC,QAC6C;EAC7C,OAAO,UAAU,MAAM,EACtB,gBAAgB,OACjB,CAAC;CACF;CAEA,OACC,IAC0D;EAC1D,IAAI,CAAC,KAAK,OACT,MAAM,IAAI,MACT,6DACD;EAED,IAAI,CAAC,KAAK,gBACT,MAAM,IAAI,MACT,2EACD;EAqBD,OAAO,IAlBW,MACjB,KAAK,OACL,IACA,KAAK,gBACL,KAAK,UACL,KAAK,WACL,KAAK,SACL,KAAK,YACL,KAAK,OACL,KAAK,WASK;CACZ;AACD;;;ACpJA,MAAa,IAAI,IAAI,aAAa"}

package/dist/rest-api.cjs

@@ -1,14 +1,9 @@
-const require_chunk = require('./chunk-DWy1uDak.cjs');
-const require_construct_interface = require('./construct-interface-BfjcOD_E.cjs');
-require('./Construct-CyS3RpTL.cjs');
-require('./functions-i_la-N5r.cjs');
-const require_EndpointFactory = require('./EndpointFactory-CdWB7wPw.cjs');
-require('./clone-Dy0cR2SZ.cjs');
-require('./Endpoint-DcWXE-SZ.cjs');
-const require_surfaceEnv = require('./surfaceEnv-BFXEms2f.cjs');
-const __geekmidas_manifest = require_chunk.__toESM(require("@geekmidas/manifest"));
-const __geekmidas_logger_console = require_chunk.__toESM(require("@geekmidas/logger/console"));
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_construct_interface = require("./construct-interface.cjs");
+const require_EndpointFactory = require("./EndpointFactory-M8OQKZRY.cjs");
+const require_surfaceEnv = require("./surfaceEnv-CNimK76p.cjs");
+let _geekmidas_manifest = require("@geekmidas/manifest");
+let _geekmidas_logger_console = require("@geekmidas/logger/console");
 //#region src/rest-api.ts
 /**
 * What is *not* here, and why.
@@ -26,6 +21,9 @@ const __geekmidas_logger_console = require_chunk.__toESM(require("@geekmidas/log
 * What is left is what the *process* is rather than what a route may reach.
 */
 var RestApi = class RestApi {
+	config;
+	dependencies;
+	authenticator;
 	id;
 	/**
 	* Declared once and read by both `declare()` and anything that consumes this
@@ -56,14 +54,14 @@ var RestApi = class RestApi {
 		this.config = config;
 		this.dependencies = dependencies;
 		this.authenticator = authenticator;
-		const canonical = (0, __geekmidas_manifest.canonicalId)(id);
+		const canonical = (0, _geekmidas_manifest.canonicalId)(id);
 		this.id = canonical;
 		this.keys = {
-			url: (0, __geekmidas_manifest.provideKey)(canonical, "url"),
-			trustedOrigins: (0, __geekmidas_manifest.provideKey)(canonical, "trustedOrigins"),
-			cookieDomain: (0, __geekmidas_manifest.provideKey)(canonical, "cookieDomain")
+			url: (0, _geekmidas_manifest.provideKey)(canonical, "url"),
+			trustedOrigins: (0, _geekmidas_manifest.provideKey)(canonical, "trustedOrigins"),
+			cookieDomain: (0, _geekmidas_manifest.provideKey)(canonical, "cookieDomain")
 		};
-		this.logger = config.logger ?? __geekmidas_logger_console.DEFAULT_LOGGER;
+		this.logger = config.logger ?? _geekmidas_logger_console.DEFAULT_LOGGER;
 		this.telescope = config.telescope;
 		this.envParser = require_surfaceEnv.envParserFor(config.envParser ? {
 			id: canonical,
@@ -179,7 +177,7 @@ var RestApi = class RestApi {
 		}];
 	}
 };
-
 //#endregion
 exports.RestApi = RestApi;
+
 //# sourceMappingURL=rest-api.cjs.map

package/dist/rest-api.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"rest-api.cjs","names":["id: ConstructName<TName>","config: RestApiConfig<TAuthorizers>","dependencies: readonly Dependency[]","authenticator?: string","DEFAULT_LOGGER","EndpointFactory","path: TPath","construct: Declarable","constructs: readonly Declarable[]","edgeTo"],"sources":["../src/rest-api.ts"],"sourcesContent":["/**\n * `RestApi` — the application's own HTTP surface, declared.\n *\n * Everything an app serves already existed; what did not exist was a *node* for\n * it. Without one, three things that are properties of the graph had to be\n * written down somewhere else: which origins the API accepts, which origins the\n * auth server trusts, and which URL a frontend is built against. All three were\n * being derived by walking the workspace config for ports — a second mechanism,\n * running beside the graph and answering the same question worse, since it can\n * only ever describe what this repo happens to run.\n *\n * With the surface declared, all three become one edge read backwards: a\n * consumer depends on the API, and *that* is the CORS entry, the trusted origin,\n * and the build-time URL. Nothing enumerates its own callers.\n *\n * ```ts\n * export const api = new RestApi('Api', {\n *   authorizers: ['session'],\n *   defaultAuthorizer: 'session',\n * });\n * ```\n */\n\nimport type { EnvironmentParser } from '@geekmidas/envkit';\nimport type { Logger } from '@geekmidas/logger';\nimport { DEFAULT_LOGGER } from '@geekmidas/logger/console';\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\ttype Dependency,\n\tprovideKey,\n} from '@geekmidas/manifest';\nimport type { Telescope } from '@geekmidas/telescope';\nimport { type Declarable, edgeTo } from './construct-interface';\nimport type { BuiltInSecuritySchemeId } from './endpoints/Authorizer';\nimport { EndpointFactory } from './endpoints/EndpointFactory';\nimport { envParserFor } from './endpoints/surfaceEnv';\n\nexport interface RestApiConfig<\n\t// `readonly []` rather than `readonly string[]`: a surface that declares no\n\t// authorizers of its own should narrow `defaultAuthorizer` to the built-ins\n\t// and `'none'`, not widen it back to any string.\n\tTAuthorizers extends readonly string[] = readonly [],\n> {\n\t/**\n\t * The app that serves this surface, relative to the workspace root —\n\t * `'apps/api'`, or `'.'` in a single-app project.\n\t *\n\t * Required. It was inferred from the id (`apps/<kebab-id>`, or the root\n\t * when no such directory existed), which meant a surface's home was\n\t * whatever happened to be on disk. It is where the app's `package.json`\n\t * and base `tsconfig.json` are, and which build serves this surface. It\n\t * does not change discovery: constructs still load from the workspace's\n\t * `constructs` glob.\n\t */\n\tpath: string;\n\t/**\n\t * CORS tunables. The *origins* are never here — they are read off the\n\t * constructs that declared an edge to this surface, which is the whole point\n\t * of declaring one. These are the parts a graph cannot answer.\n\t */\n\tcors?: {\n\t\tmaxAge?: number;\n\t\tcredentials?: boolean;\n\t\tallowHeaders?: readonly string[];\n\t\texposeHeaders?: readonly string[];\n\t};\n\t/**\n\t * The authorizer names this surface exposes. Names only — what verifies a\n\t * request legitimately differs between local and deployed, so the mechanism\n\t * belongs to the target and never to portable code.\n\t */\n\tauthorizers?: TAuthorizers;\n\t/**\n\t * The authorizer applied to an endpoint that names none.\n\t *\n\t * Required, and `'none'` is a valid answer that has to be typed out. The\n\t * alternative is an API that ships open because a field was left off, which\n\t * is the one default worth refusing to have.\n\t *\n\t * It was called `default`, which said what it was to the type and nothing\n\t * to the reader: next to `authorizers: ['iam']`, a bare `default: 'none'`\n\t * could be defaulting the runtime or the target. The manifest has always\n\t * called it `defaultAuthorizer` and the factory `defaultAuthorizerName`;\n\t * this is the same fact under the same name.\n\t *\n\t * Typed from `authorizers`, so it can only name one this surface exposes —\n\t * plus a built-in scheme, and `'none'`. It was a bare `string`, which let\n\t * `defaultAuthorizer: 'jwtt'` compile and every endpoint on the surface\n\t * default to an authorizer that does not exist.\n\t */\n\tdefaultAuthorizer: TAuthorizers[number] | BuiltInSecuritySchemeId | 'none';\n\t/**\n\t * The logger every endpoint on this surface runs with.\n\t *\n\t * The actual logger, not a path to one. It used to be named in config as\n\t * `logger: './config/logger'`, because the build wrote an import into each\n\t * generated handler and a generator can print a specifier but not an object.\n\t * Endpoints built from the surface carry it, so there is nothing to print\n\t * and nothing to keep in step with a moved file.\n\t */\n\tlogger?: Logger;\n\t/**\n\t * The environment parser every endpoint on this surface runs with.\n\t *\n\t * Same reason as `logger`, and the same field it replaces —\n\t * `envParser: './config/env#envParser'`, a module path with an export name\n\t * appended, parsed by us, checked by nothing.\n\t */\n\tenvParser?: EnvironmentParser<{}>;\n\t/**\n\t * The Telescope instance this surface's entry mounts.\n\t *\n\t * The actual instance, for the reason `logger` is: it used to be named as\n\t * `telescope: './config/telescope#telescope'`, a module path the build\n\t * printed an import for. The entry already imports the surface.\n\t */\n\ttelescope?: Telescope;\n}\n\n/**\n * What is *not* here, and why.\n *\n * `dependsOn`, `database`, `auditor` and `publisher` all inject a capability\n * into a handler. Putting one on the surface hands it to every route the\n * surface serves — a health check gets the database because a report needed it\n * — which is the thing least privilege forbids and the reason `.calls()` is not\n * spelled `dependsOn`. They belong to the endpoint, or to a factory branched\n * from `api.endpoints` for a group of endpoints that genuinely share them.\n *\n * `auth` is not here either: `.auth(construct)` already declares it, and a\n * second way to say the same thing is the duplication this whole model removes.\n *\n * What is left is what the *process* is rather than what a route may reach.\n */\n\nexport class RestApi<\n\tTName extends string = string,\n\tconst TAuthorizers extends readonly string[] = readonly [],\n> implements Declarable<TName>\n{\n\treadonly id: TName;\n\n\t/**\n\t * Declared once and read by both `declare()` and anything that consumes this\n\t * surface, so what the target publishes and what a consumer reads cannot\n\t * drift.\n\t */\n\treadonly keys: {\n\t\turl: string;\n\t\ttrustedOrigins: string;\n\t\tcookieDomain: string;\n\t};\n\n\t/**\n\t * The logger every endpoint on this surface runs with.\n\t *\n\t * Always defined — the surface's own if it was given one, the console\n\t * logger otherwise — so nothing downstream has to decide what to do about a\n\t * missing one. The generated entry reads it from here.\n\t */\n\treadonly logger: Logger;\n\n\t/**\n\t * The environment parser every endpoint on this surface runs with.\n\t *\n\t * Always defined, and normally the default: `process.env` merged with the\n\t * credentials `gkm dev`/`gkm exec` injected. That is what every\n\t * application's own `config/env.ts` was — boilerplate identical in every\n\t * project, and mandatory, which is a poor combination.\n\t */\n\treadonly envParser: EnvironmentParser<{}>;\n\n\t/** The Telescope instance, when this surface was given one. */\n\treadonly telescope?: Telescope;\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly config: RestApiConfig<TAuthorizers>,\n\t\t/** Internal: how `.calls()` carries edges into the copy it returns. */\n\t\tprivate readonly dependencies: readonly Dependency[] = [],\n\t\t/** Internal: how `.auth()` carries the authenticator into its copy. */\n\t\tprivate readonly authenticator?: string,\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\n\t\tthis.keys = {\n\t\t\turl: provideKey(canonical, 'url'),\n\t\t\ttrustedOrigins: provideKey(canonical, 'trustedOrigins'),\n\t\t\tcookieDomain: provideKey(canonical, 'cookieDomain'),\n\t\t};\n\n\t\tthis.logger = config.logger ?? DEFAULT_LOGGER;\n\t\tthis.telescope = config.telescope;\n\t\tthis.envParser = envParserFor(\n\t\t\tconfig.envParser\n\t\t\t\t? { id: canonical, envParser: config.envParser }\n\t\t\t\t: undefined,\n\t\t);\n\n\t\tthis.endpoints = new EndpointFactory({\n\t\t\tdefaultLogger: this.logger,\n\t\t\t...(config.authorizers\n\t\t\t\t? {\n\t\t\t\t\t\tavailableAuthorizers: config.authorizers.map((name) => ({ name })),\n\t\t\t\t\t}\n\t\t\t\t: {}),\n\t\t\t// `'none'` reaches the factory as no default at all, which is what\n\t\t\t// public means to an endpoint that names no authorizer.\n\t\t\t...(config.defaultAuthorizer && config.defaultAuthorizer !== 'none'\n\t\t\t\t? { defaultAuthorizerName: config.defaultAuthorizer }\n\t\t\t\t: {}),\n\t\t\tsurface: { id: this.id, envParser: this.envParser },\n\t\t});\n\t}\n\n\t/**\n\t * This surface's endpoint factory.\n\t *\n\t * `api.get('/users')` is the short form and covers most routes. Reach for\n\t * this one when a *group* of endpoints shares something a single route would\n\t * otherwise repeat — a database, an auditor, a publisher:\n\t *\n\t * ```ts\n\t * const audited = api.endpoints.database(db).auditor(AuditStore);\n\t * export const createUser = audited.post('/users').handle(...);\n\t * ```\n\t *\n\t * A factory branched from here keeps the surface, so its endpoints still\n\t * know which API serves them. That is deliberately narrower than putting the\n\t * same thing in the surface's own config: a group opts in, where a surface\n\t * would grant it to every route it serves.\n\t */\n\treadonly endpoints: EndpointFactory<[], '', Logger>;\n\n\t/** `api.get('/users')` — sugar for `api.endpoints.get('/users')`. */\n\tget<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.get(path);\n\t}\n\n\tpost<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.post(path);\n\t}\n\n\tput<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.put(path);\n\t}\n\n\tpatch<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.patch(path);\n\t}\n\n\tdelete<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.delete(path);\n\t}\n\n\toptions<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.options(path);\n\t}\n\n\t/**\n\t * What authenticates this surface.\n\t *\n\t * An edge like `.calls()` — the auth server learns this origin, and the two\n\t * share a cookie domain — but a named one, because *who authenticates me* is\n\t * a different fact from *who I happen to call*, and only one of them decides\n\t * what a request is allowed to be. A surface with two of the first is a\n\t * mistake; two of the second is Tuesday.\n\t *\n\t * It records the id, not a client. Every endpoint consumes the same thing —\n\t * `verify(request) → Session | null` — and that is what every provider\n\t * shares, whether the server is mounted in this process, deployed beside it,\n\t * or an OIDC issuer somebody else runs.\n\t */\n\tauth(construct: Declarable): RestApi<TName, TAuthorizers> {\n\t\treturn new RestApi<TName, TAuthorizers>(\n\t\t\tthis.id as ConstructName<TName>,\n\t\t\tthis.config,\n\t\t\t[...this.dependencies, edgeTo(construct)],\n\t\t\tconstruct.id,\n\t\t);\n\t}\n\n\t/**\n\t * Other surfaces this one calls.\n\t *\n\t * **Not `.dependsOn()`, and the difference matters.** An endpoint's\n\t * `.dependsOn()` injects a client into that handler and grants it exactly\n\t * what it named. This grants nothing and injects nothing: it records that\n\t * this API calls another surface, which is what puts this API's origin on\n\t * that surface's trusted-origin list.\n\t *\n\t * Spelling it `dependsOn` would invite the thing least privilege forbids —\n\t * every route on the surface receiving whatever the surface named.\n\t *\n\t * Immutable, like every other builder here.\n\t */\n\tcalls(constructs: readonly Declarable[]): RestApi<TName, TAuthorizers> {\n\t\treturn new RestApi<TName, TAuthorizers>(\n\t\t\tthis.id as ConstructName<TName>,\n\t\t\tthis.config,\n\t\t\t[...this.dependencies, ...constructs.map(edgeTo)],\n\t\t\tthis.authenticator,\n\t\t);\n\t}\n\n\t/**\n\t * One surface node, with its endpoints left to the build.\n\t *\n\t * The three provided keys are one fact about this surface and two about its\n\t * callers. Declaring the caller-derived pair here rather than having the\n\t * target invent them is what makes the contract checkable: a target that\n\t * resolves no origins is caught against this list instead of being noticed\n\t * when a browser is refused in production.\n\t */\n\tdeclare(): Declaration[] {\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'rest-api',\n\t\t\t\tid: this.id,\n\t\t\t\tpath: this.config.path,\n\t\t\t\t...(this.config.telescope ? { telescope: true } : {}),\n\t\t\t\t...(this.config.cors ? { cors: this.config.cors } : {}),\n\t\t\t\t...(this.authenticator ? { auth: this.authenticator } : {}),\n\t\t\t\t// Filled by the build, which already generates one handler per\n\t\t\t\t// endpoint and knows the path it wrote it to. A surface that\n\t\t\t\t// enumerates its own routes statically — an auth server's single\n\t\t\t\t// wildcard — puts them here instead.\n\t\t\t\tendpoints: [],\n\t\t\t\t...(this.dependencies.length ? { calls: this.dependencies } : {}),\n\t\t\t\t...(this.config.authorizers?.length\n\t\t\t\t\t? { authorizers: this.config.authorizers }\n\t\t\t\t\t: {}),\n\t\t\t\tdefaultAuthorizer: this.config.defaultAuthorizer,\n\t\t\t\tprovides: [\n\t\t\t\t\tthis.keys.url,\n\t\t\t\t\tthis.keys.trustedOrigins,\n\t\t\t\t\tthis.keys.cookieDomain,\n\t\t\t\t],\n\t\t\t},\n\t\t];\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAyIA,IAAa,UAAb,MAAa,QAIb;CACC,AAAS;;;;;;CAOT,AAAS;;;;;;;;CAaT,AAAS;;;;;;;;;CAUT,AAAS;;CAGT,AAAS;CAET,YACCA,IACiBC,QAEAC,eAAsC,CAAE,GAExCC,eAChB;EALgB;EAEA;EAEA;EAEjB,MAAM,YAAY,sCAAY,GAAa;AAE3C,OAAK,KAAK;AAEV,OAAK,OAAO;GACX,KAAK,qCAAW,WAAW,MAAM;GACjC,gBAAgB,qCAAW,WAAW,iBAAiB;GACvD,cAAc,qCAAW,WAAW,eAAe;EACnD;AAED,OAAK,SAAS,OAAO,UAAUC;AAC/B,OAAK,YAAY,OAAO;AACxB,OAAK,YAAY,gCAChB,OAAO,YACJ;GAAE,IAAI;GAAW,WAAW,OAAO;EAAW,WAEjD;AAED,OAAK,YAAY,IAAIC,wCAAgB;GACpC,eAAe,KAAK;GACpB,GAAI,OAAO,cACR,EACA,sBAAsB,OAAO,YAAY,IAAI,CAAC,UAAU,EAAE,KAAM,GAAE,CAClE,IACA,CAAE;GAGL,GAAI,OAAO,qBAAqB,OAAO,sBAAsB,SAC1D,EAAE,uBAAuB,OAAO,kBAAmB,IACnD,CAAE;GACL,SAAS;IAAE,IAAI,KAAK;IAAI,WAAW,KAAK;GAAW;EACnD;CACD;;;;;;;;;;;;;;;;;;CAmBD,AAAS;;CAGT,IAA0BC,MAAa;AACtC,SAAO,KAAK,UAAU,IAAI,KAAK;CAC/B;CAED,KAA2BA,MAAa;AACvC,SAAO,KAAK,UAAU,KAAK,KAAK;CAChC;CAED,IAA0BA,MAAa;AACtC,SAAO,KAAK,UAAU,IAAI,KAAK;CAC/B;CAED,MAA4BA,MAAa;AACxC,SAAO,KAAK,UAAU,MAAM,KAAK;CACjC;CAED,OAA6BA,MAAa;AACzC,SAAO,KAAK,UAAU,OAAO,KAAK;CAClC;CAED,QAA8BA,MAAa;AAC1C,SAAO,KAAK,UAAU,QAAQ,KAAK;CACnC;;;;;;;;;;;;;;;CAgBD,KAAKC,WAAqD;AACzD,SAAO,IAAI,QACV,KAAK,IACL,KAAK,QACL,CAAC,GAAG,KAAK,cAAc,mCAAO,UAAU,AAAC,GACzC,UAAU;CAEX;;;;;;;;;;;;;;;CAgBD,MAAMC,YAAiE;AACtE,SAAO,IAAI,QACV,KAAK,IACL,KAAK,QACL,CAAC,GAAG,KAAK,cAAc,GAAG,WAAW,IAAIC,mCAAO,AAAC,GACjD,KAAK;CAEN;;;;;;;;;;CAWD,UAAyB;AACxB,SAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,MAAM,KAAK,OAAO;GAClB,GAAI,KAAK,OAAO,YAAY,EAAE,WAAW,KAAM,IAAG,CAAE;GACpD,GAAI,KAAK,OAAO,OAAO,EAAE,MAAM,KAAK,OAAO,KAAM,IAAG,CAAE;GACtD,GAAI,KAAK,gBAAgB,EAAE,MAAM,KAAK,cAAe,IAAG,CAAE;GAK1D,WAAW,CAAE;GACb,GAAI,KAAK,aAAa,SAAS,EAAE,OAAO,KAAK,aAAc,IAAG,CAAE;GAChE,GAAI,KAAK,OAAO,aAAa,SAC1B,EAAE,aAAa,KAAK,OAAO,YAAa,IACxC,CAAE;GACL,mBAAmB,KAAK,OAAO;GAC/B,UAAU;IACT,KAAK,KAAK;IACV,KAAK,KAAK;IACV,KAAK,KAAK;GACV;EACD,CACD;CACD;AACD"}
+{"version":3,"file":"rest-api.cjs","names":["canonicalId","provideKey","DEFAULT_LOGGER","envParserFor","EndpointFactory","edgeTo"],"sources":["../src/rest-api.ts"],"sourcesContent":["/**\n * `RestApi` — the application's own HTTP surface, declared.\n *\n * Everything an app serves already existed; what did not exist was a *node* for\n * it. Without one, three things that are properties of the graph had to be\n * written down somewhere else: which origins the API accepts, which origins the\n * auth server trusts, and which URL a frontend is built against. All three were\n * being derived by walking the workspace config for ports — a second mechanism,\n * running beside the graph and answering the same question worse, since it can\n * only ever describe what this repo happens to run.\n *\n * With the surface declared, all three become one edge read backwards: a\n * consumer depends on the API, and *that* is the CORS entry, the trusted origin,\n * and the build-time URL. Nothing enumerates its own callers.\n *\n * ```ts\n * export const api = new RestApi('Api', {\n *   authorizers: ['session'],\n *   defaultAuthorizer: 'session',\n * });\n * ```\n */\n\nimport type { EnvironmentParser } from '@geekmidas/envkit';\nimport type { Logger } from '@geekmidas/logger';\nimport { DEFAULT_LOGGER } from '@geekmidas/logger/console';\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\ttype Dependency,\n\tprovideKey,\n} from '@geekmidas/manifest';\nimport type { Telescope } from '@geekmidas/telescope';\nimport { type Declarable, edgeTo } from './construct-interface';\nimport type { BuiltInSecuritySchemeId } from './endpoints/Authorizer';\nimport { EndpointFactory } from './endpoints/EndpointFactory';\nimport { envParserFor } from './endpoints/surfaceEnv';\n\nexport interface RestApiConfig<\n\t// `readonly []` rather than `readonly string[]`: a surface that declares no\n\t// authorizers of its own should narrow `defaultAuthorizer` to the built-ins\n\t// and `'none'`, not widen it back to any string.\n\tTAuthorizers extends readonly string[] = readonly [],\n> {\n\t/**\n\t * The app that serves this surface, relative to the workspace root —\n\t * `'apps/api'`, or `'.'` in a single-app project.\n\t *\n\t * Required. It was inferred from the id (`apps/<kebab-id>`, or the root\n\t * when no such directory existed), which meant a surface's home was\n\t * whatever happened to be on disk. It is where the app's `package.json`\n\t * and base `tsconfig.json` are, and which build serves this surface. It\n\t * does not change discovery: constructs still load from the workspace's\n\t * `constructs` glob.\n\t */\n\tpath: string;\n\t/**\n\t * CORS tunables. The *origins* are never here — they are read off the\n\t * constructs that declared an edge to this surface, which is the whole point\n\t * of declaring one. These are the parts a graph cannot answer.\n\t */\n\tcors?: {\n\t\tmaxAge?: number;\n\t\tcredentials?: boolean;\n\t\tallowHeaders?: readonly string[];\n\t\texposeHeaders?: readonly string[];\n\t};\n\t/**\n\t * The authorizer names this surface exposes. Names only — what verifies a\n\t * request legitimately differs between local and deployed, so the mechanism\n\t * belongs to the target and never to portable code.\n\t */\n\tauthorizers?: TAuthorizers;\n\t/**\n\t * The authorizer applied to an endpoint that names none.\n\t *\n\t * Required, and `'none'` is a valid answer that has to be typed out. The\n\t * alternative is an API that ships open because a field was left off, which\n\t * is the one default worth refusing to have.\n\t *\n\t * It was called `default`, which said what it was to the type and nothing\n\t * to the reader: next to `authorizers: ['iam']`, a bare `default: 'none'`\n\t * could be defaulting the runtime or the target. The manifest has always\n\t * called it `defaultAuthorizer` and the factory `defaultAuthorizerName`;\n\t * this is the same fact under the same name.\n\t *\n\t * Typed from `authorizers`, so it can only name one this surface exposes —\n\t * plus a built-in scheme, and `'none'`. It was a bare `string`, which let\n\t * `defaultAuthorizer: 'jwtt'` compile and every endpoint on the surface\n\t * default to an authorizer that does not exist.\n\t */\n\tdefaultAuthorizer: TAuthorizers[number] | BuiltInSecuritySchemeId | 'none';\n\t/**\n\t * The logger every endpoint on this surface runs with.\n\t *\n\t * The actual logger, not a path to one. It used to be named in config as\n\t * `logger: './config/logger'`, because the build wrote an import into each\n\t * generated handler and a generator can print a specifier but not an object.\n\t * Endpoints built from the surface carry it, so there is nothing to print\n\t * and nothing to keep in step with a moved file.\n\t */\n\tlogger?: Logger;\n\t/**\n\t * The environment parser every endpoint on this surface runs with.\n\t *\n\t * Same reason as `logger`, and the same field it replaces —\n\t * `envParser: './config/env#envParser'`, a module path with an export name\n\t * appended, parsed by us, checked by nothing.\n\t */\n\tenvParser?: EnvironmentParser<{}>;\n\t/**\n\t * The Telescope instance this surface's entry mounts.\n\t *\n\t * The actual instance, for the reason `logger` is: it used to be named as\n\t * `telescope: './config/telescope#telescope'`, a module path the build\n\t * printed an import for. The entry already imports the surface.\n\t */\n\ttelescope?: Telescope;\n}\n\n/**\n * What is *not* here, and why.\n *\n * `dependsOn`, `database`, `auditor` and `publisher` all inject a capability\n * into a handler. Putting one on the surface hands it to every route the\n * surface serves — a health check gets the database because a report needed it\n * — which is the thing least privilege forbids and the reason `.calls()` is not\n * spelled `dependsOn`. They belong to the endpoint, or to a factory branched\n * from `api.endpoints` for a group of endpoints that genuinely share them.\n *\n * `auth` is not here either: `.auth(construct)` already declares it, and a\n * second way to say the same thing is the duplication this whole model removes.\n *\n * What is left is what the *process* is rather than what a route may reach.\n */\n\nexport class RestApi<\n\tTName extends string = string,\n\tconst TAuthorizers extends readonly string[] = readonly [],\n> implements Declarable<TName>\n{\n\treadonly id: TName;\n\n\t/**\n\t * Declared once and read by both `declare()` and anything that consumes this\n\t * surface, so what the target publishes and what a consumer reads cannot\n\t * drift.\n\t */\n\treadonly keys: {\n\t\turl: string;\n\t\ttrustedOrigins: string;\n\t\tcookieDomain: string;\n\t};\n\n\t/**\n\t * The logger every endpoint on this surface runs with.\n\t *\n\t * Always defined — the surface's own if it was given one, the console\n\t * logger otherwise — so nothing downstream has to decide what to do about a\n\t * missing one. The generated entry reads it from here.\n\t */\n\treadonly logger: Logger;\n\n\t/**\n\t * The environment parser every endpoint on this surface runs with.\n\t *\n\t * Always defined, and normally the default: `process.env` merged with the\n\t * credentials `gkm dev`/`gkm exec` injected. That is what every\n\t * application's own `config/env.ts` was — boilerplate identical in every\n\t * project, and mandatory, which is a poor combination.\n\t */\n\treadonly envParser: EnvironmentParser<{}>;\n\n\t/** The Telescope instance, when this surface was given one. */\n\treadonly telescope?: Telescope;\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly config: RestApiConfig<TAuthorizers>,\n\t\t/** Internal: how `.calls()` carries edges into the copy it returns. */\n\t\tprivate readonly dependencies: readonly Dependency[] = [],\n\t\t/** Internal: how `.auth()` carries the authenticator into its copy. */\n\t\tprivate readonly authenticator?: string,\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\n\t\tthis.keys = {\n\t\t\turl: provideKey(canonical, 'url'),\n\t\t\ttrustedOrigins: provideKey(canonical, 'trustedOrigins'),\n\t\t\tcookieDomain: provideKey(canonical, 'cookieDomain'),\n\t\t};\n\n\t\tthis.logger = config.logger ?? DEFAULT_LOGGER;\n\t\tthis.telescope = config.telescope;\n\t\tthis.envParser = envParserFor(\n\t\t\tconfig.envParser\n\t\t\t\t? { id: canonical, envParser: config.envParser }\n\t\t\t\t: undefined,\n\t\t);\n\n\t\tthis.endpoints = new EndpointFactory({\n\t\t\tdefaultLogger: this.logger,\n\t\t\t...(config.authorizers\n\t\t\t\t? {\n\t\t\t\t\t\tavailableAuthorizers: config.authorizers.map((name) => ({ name })),\n\t\t\t\t\t}\n\t\t\t\t: {}),\n\t\t\t// `'none'` reaches the factory as no default at all, which is what\n\t\t\t// public means to an endpoint that names no authorizer.\n\t\t\t...(config.defaultAuthorizer && config.defaultAuthorizer !== 'none'\n\t\t\t\t? { defaultAuthorizerName: config.defaultAuthorizer }\n\t\t\t\t: {}),\n\t\t\tsurface: { id: this.id, envParser: this.envParser },\n\t\t});\n\t}\n\n\t/**\n\t * This surface's endpoint factory.\n\t *\n\t * `api.get('/users')` is the short form and covers most routes. Reach for\n\t * this one when a *group* of endpoints shares something a single route would\n\t * otherwise repeat — a database, an auditor, a publisher:\n\t *\n\t * ```ts\n\t * const audited = api.endpoints.database(db).auditor(AuditStore);\n\t * export const createUser = audited.post('/users').handle(...);\n\t * ```\n\t *\n\t * A factory branched from here keeps the surface, so its endpoints still\n\t * know which API serves them. That is deliberately narrower than putting the\n\t * same thing in the surface's own config: a group opts in, where a surface\n\t * would grant it to every route it serves.\n\t */\n\treadonly endpoints: EndpointFactory<[], '', Logger>;\n\n\t/** `api.get('/users')` — sugar for `api.endpoints.get('/users')`. */\n\tget<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.get(path);\n\t}\n\n\tpost<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.post(path);\n\t}\n\n\tput<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.put(path);\n\t}\n\n\tpatch<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.patch(path);\n\t}\n\n\tdelete<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.delete(path);\n\t}\n\n\toptions<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.options(path);\n\t}\n\n\t/**\n\t * What authenticates this surface.\n\t *\n\t * An edge like `.calls()` — the auth server learns this origin, and the two\n\t * share a cookie domain — but a named one, because *who authenticates me* is\n\t * a different fact from *who I happen to call*, and only one of them decides\n\t * what a request is allowed to be. A surface with two of the first is a\n\t * mistake; two of the second is Tuesday.\n\t *\n\t * It records the id, not a client. Every endpoint consumes the same thing —\n\t * `verify(request) → Session | null` — and that is what every provider\n\t * shares, whether the server is mounted in this process, deployed beside it,\n\t * or an OIDC issuer somebody else runs.\n\t */\n\tauth(construct: Declarable): RestApi<TName, TAuthorizers> {\n\t\treturn new RestApi<TName, TAuthorizers>(\n\t\t\tthis.id as ConstructName<TName>,\n\t\t\tthis.config,\n\t\t\t[...this.dependencies, edgeTo(construct)],\n\t\t\tconstruct.id,\n\t\t);\n\t}\n\n\t/**\n\t * Other surfaces this one calls.\n\t *\n\t * **Not `.dependsOn()`, and the difference matters.** An endpoint's\n\t * `.dependsOn()` injects a client into that handler and grants it exactly\n\t * what it named. This grants nothing and injects nothing: it records that\n\t * this API calls another surface, which is what puts this API's origin on\n\t * that surface's trusted-origin list.\n\t *\n\t * Spelling it `dependsOn` would invite the thing least privilege forbids —\n\t * every route on the surface receiving whatever the surface named.\n\t *\n\t * Immutable, like every other builder here.\n\t */\n\tcalls(constructs: readonly Declarable[]): RestApi<TName, TAuthorizers> {\n\t\treturn new RestApi<TName, TAuthorizers>(\n\t\t\tthis.id as ConstructName<TName>,\n\t\t\tthis.config,\n\t\t\t[...this.dependencies, ...constructs.map(edgeTo)],\n\t\t\tthis.authenticator,\n\t\t);\n\t}\n\n\t/**\n\t * One surface node, with its endpoints left to the build.\n\t *\n\t * The three provided keys are one fact about this surface and two about its\n\t * callers. Declaring the caller-derived pair here rather than having the\n\t * target invent them is what makes the contract checkable: a target that\n\t * resolves no origins is caught against this list instead of being noticed\n\t * when a browser is refused in production.\n\t */\n\tdeclare(): Declaration[] {\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'rest-api',\n\t\t\t\tid: this.id,\n\t\t\t\tpath: this.config.path,\n\t\t\t\t...(this.config.telescope ? { telescope: true } : {}),\n\t\t\t\t...(this.config.cors ? { cors: this.config.cors } : {}),\n\t\t\t\t...(this.authenticator ? { auth: this.authenticator } : {}),\n\t\t\t\t// Filled by the build, which already generates one handler per\n\t\t\t\t// endpoint and knows the path it wrote it to. A surface that\n\t\t\t\t// enumerates its own routes statically — an auth server's single\n\t\t\t\t// wildcard — puts them here instead.\n\t\t\t\tendpoints: [],\n\t\t\t\t...(this.dependencies.length ? { calls: this.dependencies } : {}),\n\t\t\t\t...(this.config.authorizers?.length\n\t\t\t\t\t? { authorizers: this.config.authorizers }\n\t\t\t\t\t: {}),\n\t\t\t\tdefaultAuthorizer: this.config.defaultAuthorizer,\n\t\t\t\tprovides: [\n\t\t\t\t\tthis.keys.url,\n\t\t\t\t\tthis.keys.trustedOrigins,\n\t\t\t\t\tthis.keys.cookieDomain,\n\t\t\t\t],\n\t\t\t},\n\t\t];\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAyIA,IAAa,UAAb,MAAa,QAIb;CAsCmB;CAEA;CAEA;CAzClB;;;;;;CAOA;;;;;;;;CAaA;;;;;;;;;CAUA;;CAGA;CAEA,YACC,IACA,QAEA,eAAuD,CAAC,GAExD,eACC;EALgB,KAAA,SAAA;EAEA,KAAA,eAAA;EAEA,KAAA,gBAAA;EAEjB,MAAM,aAAA,GAAYA,oBAAAA,YAAAA,CAAY,EAAY;EAE1C,KAAK,KAAK;EAEV,KAAK,OAAO;GACX,MAAA,GAAKC,oBAAAA,WAAAA,CAAW,WAAW,KAAK;GAChC,iBAAA,GAAgBA,oBAAAA,WAAAA,CAAW,WAAW,gBAAgB;GACtD,eAAA,GAAcA,oBAAAA,WAAAA,CAAW,WAAW,cAAc;EACnD;EAEA,KAAK,SAAS,OAAO,UAAUC,0BAAAA;EAC/B,KAAK,YAAY,OAAO;EACxB,KAAK,YAAYC,mBAAAA,aAChB,OAAO,YACJ;GAAE,IAAI;GAAW,WAAW,OAAO;EAAU,IAC7C,KAAA,CACJ;EAEA,KAAK,YAAY,IAAIC,wBAAAA,gBAAgB;GACpC,eAAe,KAAK;GACpB,GAAI,OAAO,cACR,EACA,sBAAsB,OAAO,YAAY,KAAK,UAAU,EAAE,KAAK,EAAE,EAClE,IACC,CAAC;GAGJ,GAAI,OAAO,qBAAqB,OAAO,sBAAsB,SAC1D,EAAE,uBAAuB,OAAO,kBAAkB,IAClD,CAAC;GACJ,SAAS;IAAE,IAAI,KAAK;IAAI,WAAW,KAAK;GAAU;EACnD,CAAC;CACF;;;;;;;;;;;;;;;;;;CAmBA;;CAGA,IAA0B,MAAa;EACtC,OAAO,KAAK,UAAU,IAAI,IAAI;CAC/B;CAEA,KAA2B,MAAa;EACvC,OAAO,KAAK,UAAU,KAAK,IAAI;CAChC;CAEA,IAA0B,MAAa;EACtC,OAAO,KAAK,UAAU,IAAI,IAAI;CAC/B;CAEA,MAA4B,MAAa;EACxC,OAAO,KAAK,UAAU,MAAM,IAAI;CACjC;CAEA,OAA6B,MAAa;EACzC,OAAO,KAAK,UAAU,OAAO,IAAI;CAClC;CAEA,QAA8B,MAAa;EAC1C,OAAO,KAAK,UAAU,QAAQ,IAAI;CACnC;;;;;;;;;;;;;;;CAgBA,KAAK,WAAqD;EACzD,OAAO,IAAI,QACV,KAAK,IACL,KAAK,QACL,CAAC,GAAG,KAAK,cAAcC,4BAAAA,OAAO,SAAS,CAAC,GACxC,UAAU,EACX;CACD;;;;;;;;;;;;;;;CAgBA,MAAM,YAAiE;EACtE,OAAO,IAAI,QACV,KAAK,IACL,KAAK,QACL,CAAC,GAAG,KAAK,cAAc,GAAG,WAAW,IAAIA,4BAAAA,MAAM,CAAC,GAChD,KAAK,aACN;CACD;;;;;;;;;;CAWA,UAAyB;EACxB,OAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,MAAM,KAAK,OAAO;GAClB,GAAI,KAAK,OAAO,YAAY,EAAE,WAAW,KAAK,IAAI,CAAC;GACnD,GAAI,KAAK,OAAO,OAAO,EAAE,MAAM,KAAK,OAAO,KAAK,IAAI,CAAC;GACrD,GAAI,KAAK,gBAAgB,EAAE,MAAM,KAAK,cAAc,IAAI,CAAC;GAKzD,WAAW,CAAC;GACZ,GAAI,KAAK,aAAa,SAAS,EAAE,OAAO,KAAK,aAAa,IAAI,CAAC;GAC/D,GAAI,KAAK,OAAO,aAAa,SAC1B,EAAE,aAAa,KAAK,OAAO,YAAY,IACvC,CAAC;GACJ,mBAAmB,KAAK,OAAO;GAC/B,UAAU;IACT,KAAK,KAAK;IACV,KAAK,KAAK;IACV,KAAK,KAAK;GACX;EACD,CACD;CACD;AACD"}

package/dist/rest-api.d.cts

@@ -1,17 +1,12 @@
-import "./Construct-C0ijr2qp.cjs";
-import "./index-D24Xm79M.cjs";
-import { Declarable } from "./construct-interface-D9d4Gm4p.cjs";
-import "./types-BlAkSuGI.cjs";
-import { BuiltInSecuritySchemeId } from "./Endpoint-dav89W6-.cjs";
-import { EndpointBuilder, EndpointFactory, RemoveTrailingSlash } from "./index-Bd5FqCoe.cjs";
+import { r as Declarable } from "./construct-interface-DgXTJcOD.cjs";
+import { S as BuiltInSecuritySchemeId } from "./Endpoint-C6yyHpRS.cjs";
+import { d as EndpointBuilder, l as EndpointFactory, u as RemoveTrailingSlash } from "./index-BPSZ_Lp_.cjs";
 import { EnvironmentParser } from "@geekmidas/envkit";
 import { Logger } from "@geekmidas/logger";
 import { ConstructName, Declaration, Dependency } from "@geekmidas/manifest";
 import { Telescope } from "@geekmidas/telescope";
-
 //#region src/rest-api.d.ts
-
-interface RestApiConfig<TAuthorizers extends readonly string[] = readonly []> {
+export interface RestApiConfig<TAuthorizers extends readonly string[] = readonly []> {
   /**
    * The app that serves this surface, relative to the workspace root —
    * `'apps/api'`, or `'.'` in a single-app project.
@@ -102,7 +97,7 @@ interface RestApiConfig<TAuthorizers extends readonly string[] = readonly []> {
  *
  * What is left is what the *process* is rather than what a route may reach.
  */
-declare class RestApi<TName extends string = string, const TAuthorizers extends readonly string[] = readonly []> implements Declarable<TName> {
+export declare class RestApi<TName extends string = string, const TAuthorizers extends readonly string[] = readonly []> implements Declarable<TName> {
   private readonly config;
   /** Internal: how `.calls()` carries edges into the copy it returns. */
   private readonly dependencies;
@@ -138,8 +133,10 @@ declare class RestApi<TName extends string = string, const TAuthorizers extends
   readonly envParser: EnvironmentParser<{}>;
   /** The Telescope instance, when this surface was given one. */
   readonly telescope?: Telescope;
-  constructor(id: ConstructName<TName>, config: RestApiConfig<TAuthorizers>, /** Internal: how `.calls()` carries edges into the copy it returns. */
-  dependencies?: readonly Dependency[], /** Internal: how `.auth()` carries the authenticator into its copy. */
+  constructor(id: ConstructName<TName>, config: RestApiConfig<TAuthorizers>,
+  /** Internal: how `.calls()` carries edges into the copy it returns. */
+  dependencies?: readonly Dependency[],
+  /** Internal: how `.auth()` carries the authenticator into its copy. */
   authenticator?: string | undefined);
   /**
    * This surface's endpoint factory.
@@ -160,12 +157,12 @@ declare class RestApi<TName extends string = string, const TAuthorizers extends
    */
   readonly endpoints: EndpointFactory<[], '', Logger>;
   /** `api.get('/users')` — sugar for `api.endpoints.get('/users')`. */
-  get<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "GET", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, never, undefined, string>;
-  post<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "POST", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, never, undefined, string>;
-  put<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "PUT", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, never, undefined, string>;
-  patch<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "PATCH", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, never, undefined, string>;
-  delete<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "DELETE", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, never, undefined, string>;
-  options<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "OPTIONS", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, never, undefined, string>;
+  get<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "GET", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, ExtractStorageAuditAction<NonNullable<TAuditStorage>>, undefined, string>;
+  post<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "POST", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, ExtractStorageAuditAction<NonNullable<TAuditStorage>>, undefined, string>;
+  put<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "PUT", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, ExtractStorageAuditAction<NonNullable<TAuditStorage>>, undefined, string>;
+  patch<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "PATCH", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, ExtractStorageAuditAction<NonNullable<TAuditStorage>>, undefined, string>;
+  delete<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "DELETE", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, ExtractStorageAuditAction<NonNullable<TAuditStorage>>, undefined, string>;
+  options<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "OPTIONS", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, ExtractStorageAuditAction<NonNullable<TAuditStorage>>, undefined, string>;
   /**
    * What authenticates this surface.
    *
@@ -207,7 +204,5 @@ declare class RestApi<TName extends string = string, const TAuthorizers extends
    */
   declare(): Declaration[];
 }
-//# sourceMappingURL=rest-api.d.ts.map
 //#endregion
-export { RestApi, RestApiConfig };
 //# sourceMappingURL=rest-api.d.cts.map

package/dist/rest-api.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"rest-api.d.cts","names":[],"sources":["../src/rest-api.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AAkLM,UA3IW,aA2IX,CAAA,qBAAA,SAAA,MAAA,EAAA,GAAA,SAAA,EAAA,CAAA,CAAA;EAAa;;;;;;;;;;;EAiEoB,IAAA,EAAA,MAAA;EAAA;;;;;EAID,IAAA,CAAA,EAAA;IAAA,MAAA,CAAA,EAAA,MAAA;IAAA,WAAA,CAAA,EAAA,OAAA;IAIH,YAAA,CAAA,EAAA,SAAA,MAAA,EAAA;IAAK,aAAA,CAAA,EAAA,SAAA,MAAA,EAAA;EAAA,CAAA;EAAA;;;;;EAIC,WAAA,CAAA,EAtL1B,YAsL0B;EAAA;;;;;;;;;;;;;;;;AAnHlB;;qBAhDH,uBAAuB;;;;;;;;;;WAUjC;;;;;;;;cAQG;;;;;;;;cAQA;;;;;;;;;;;;;;;;;cAmBA,8GAGA,WAAW;;;;;;eAEV;;;;;;;;;;;;;;;;;;mBAoBI;;;;;;;;;sBAUG;;uBAGC;kBAGhB,cAAc,gBACO,cAAc;0BAEC;;;;;;;;;;;;;;;;;;;sBAuDrB,wBAAwB;;kCAGZ,QAAK,gBAAA,oBAAA,uBAAA;mCAIJ,QAAK,gBAAA,oBAAA,wBAAA;kCAIN,QAAK,gBAAA,oBAAA,uBAAA;oCAIH,QAAK,gBAAA,oBAAA,yBAAA;qCAIJ,QAAK,gBAAA,oBAAA,0BAAA;sCAIJ,QAAK,gBAAA,oBAAA,2BAAA;;;;;;;;;;;;;;;kBAkBzB,aAAa,QAAQ,OAAO;;;;;;;;;;;;;;;6BAuBjB,eAAe,QAAQ,OAAO;;;;;;;;;;aAkB9C"}
+{"version":3,"file":"rest-api.d.cts","names":["_$__endpoints_EndpointFactory0.RemoveTrailingSlash","_$__endpoints0.EndpointBuilder"],"sources":["../src/rest-api.ts"],"mappings":";;;;;;;;iBAuCiB,cAIhB;;;;;;;;;;;;EAaA;;;;;;EAMA;IACC;IACA;IACA;IACA;;;;;;;EAOD,cAAc;;;;;;;;;;;;;;;;;;;EAmBd,mBAAmB,uBAAuB;;;;;;;;;;EAU1C,SAAS;;;;;;;;EAQT,YAAY;;;;;;;;EAQZ,YAAY;;;;;;;;;;;;;;;;;qBAmBA,QACZ,qCACM,iEACM,WAAW;mBAuCL;;mBAEA;;mBAEA;WAzCT,IAAI;;;;;;WAOJ;IACR;IACA;IACA;;;;;;;;;WAUQ,QAAQ;;;;;;;;;WAUR,WAAW;;WAGX,YAAY;EAGpB,YAAA,IAAI,cAAc,QACD,QAAQ,cAAc,eAEtB;;EAAA,wBAAuB,cAEvB;;EAAA;;;;;;;;;;;;;;;;;;WAqDT,WAAW,wBAAwB;;EAG5C,IAAI,sBAAsB,MAAM,QAAKC,gBAAAD,oBAAA,uBAAA,qFAAA,0BAAA,YAAA;EAIrC,KAAK,sBAAsB,MAAM,QAAKC,gBAAAD,oBAAA,wBAAA,qFAAA,0BAAA,YAAA;EAItC,IAAI,sBAAsB,MAAM,QAAKC,gBAAAD,oBAAA,uBAAA,qFAAA,0BAAA,YAAA;EAIrC,MAAM,sBAAsB,MAAM,QAAKC,gBAAAD,oBAAA,yBAAA,qFAAA,0BAAA,YAAA;EAIvC,OAAO,sBAAsB,MAAM,QAAKC,gBAAAD,oBAAA,0BAAA,qFAAA,0BAAA,YAAA;EAIxC,QAAQ,sBAAsB,MAAM,QAAKC,gBAAAD,oBAAA,2BAAA,qFAAA,0BAAA,YAAA;;;;;;;;;;;;;;;EAkBzC,KAAK,WAAW,aAAa,QAAQ,OAAO;;;;;;;;;;;;;;;EAuB5C,MAAM,qBAAqB,eAAe,QAAQ,OAAO;;;;;;;;;;EAkBzD,WAAW"}

package/dist/rest-api.d.mts

@@ -1,17 +1,12 @@
-import "./Construct-Ct8nalEi.mjs";
-import "./index-_ajboYxK.mjs";
-import { Declarable } from "./construct-interface-g5GM5pwR.mjs";
-import "./types-aKksMEWL.mjs";
-import { BuiltInSecuritySchemeId } from "./Endpoint-BjWKinFA.mjs";
-import { EndpointBuilder, EndpointFactory, RemoveTrailingSlash } from "./index-lAO9egTb.mjs";
+import { r as Declarable } from "./construct-interface-DPlxfpoS.mjs";
+import { S as BuiltInSecuritySchemeId } from "./Endpoint-DuT4TEEq.mjs";
+import { d as EndpointBuilder, l as EndpointFactory, u as RemoveTrailingSlash } from "./index-BoZ-iisU.mjs";
 import { ConstructName, Declaration, Dependency } from "@geekmidas/manifest";
 import { EnvironmentParser } from "@geekmidas/envkit";
 import { Logger } from "@geekmidas/logger";
 import { Telescope } from "@geekmidas/telescope";
-
 //#region src/rest-api.d.ts
-
-interface RestApiConfig<TAuthorizers extends readonly string[] = readonly []> {
+export interface RestApiConfig<TAuthorizers extends readonly string[] = readonly []> {
   /**
    * The app that serves this surface, relative to the workspace root —
    * `'apps/api'`, or `'.'` in a single-app project.
@@ -102,7 +97,7 @@ interface RestApiConfig<TAuthorizers extends readonly string[] = readonly []> {
  *
  * What is left is what the *process* is rather than what a route may reach.
  */
-declare class RestApi<TName extends string = string, const TAuthorizers extends readonly string[] = readonly []> implements Declarable<TName> {
+export declare class RestApi<TName extends string = string, const TAuthorizers extends readonly string[] = readonly []> implements Declarable<TName> {
   private readonly config;
   /** Internal: how `.calls()` carries edges into the copy it returns. */
   private readonly dependencies;
@@ -138,8 +133,10 @@ declare class RestApi<TName extends string = string, const TAuthorizers extends
   readonly envParser: EnvironmentParser<{}>;
   /** The Telescope instance, when this surface was given one. */
   readonly telescope?: Telescope;
-  constructor(id: ConstructName<TName>, config: RestApiConfig<TAuthorizers>, /** Internal: how `.calls()` carries edges into the copy it returns. */
-  dependencies?: readonly Dependency[], /** Internal: how `.auth()` carries the authenticator into its copy. */
+  constructor(id: ConstructName<TName>, config: RestApiConfig<TAuthorizers>,
+  /** Internal: how `.calls()` carries edges into the copy it returns. */
+  dependencies?: readonly Dependency[],
+  /** Internal: how `.auth()` carries the authenticator into its copy. */
   authenticator?: string | undefined);
   /**
    * This surface's endpoint factory.
@@ -160,12 +157,12 @@ declare class RestApi<TName extends string = string, const TAuthorizers extends
    */
   readonly endpoints: EndpointFactory<[], '', Logger>;
   /** `api.get('/users')` — sugar for `api.endpoints.get('/users')`. */
-  get<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "GET", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, never, undefined, string>;
-  post<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "POST", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, never, undefined, string>;
-  put<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "PUT", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, never, undefined, string>;
-  patch<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "PATCH", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, never, undefined, string>;
-  delete<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "DELETE", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, never, undefined, string>;
-  options<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "OPTIONS", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, never, undefined, string>;
+  get<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "GET", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, ExtractStorageAuditAction<NonNullable<TAuditStorage>>, undefined, string>;
+  post<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "POST", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, ExtractStorageAuditAction<NonNullable<TAuditStorage>>, undefined, string>;
+  put<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "PUT", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, ExtractStorageAuditAction<NonNullable<TAuditStorage>>, undefined, string>;
+  patch<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "PATCH", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, ExtractStorageAuditAction<NonNullable<TAuditStorage>>, undefined, string>;
+  delete<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "DELETE", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, ExtractStorageAuditAction<NonNullable<TAuditStorage>>, undefined, string>;
+  options<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "OPTIONS", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, ExtractStorageAuditAction<NonNullable<TAuditStorage>>, undefined, string>;
   /**
    * What authenticates this surface.
    *
@@ -207,7 +204,5 @@ declare class RestApi<TName extends string = string, const TAuthorizers extends
    */
   declare(): Declaration[];
 }
-//# sourceMappingURL=rest-api.d.ts.map
 //#endregion
-export { RestApi, RestApiConfig };
 //# sourceMappingURL=rest-api.d.mts.map

package/dist/rest-api.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"rest-api.d.mts","names":[],"sources":["../src/rest-api.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AAkLM,UA3IW,aA2IX,CAAA,qBAAA,SAAA,MAAA,EAAA,GAAA,SAAA,EAAA,CAAA,CAAA;EAAa;;;;;;;;;;;EAiEoB,IAAA,EAAA,MAAA;EAAA;;;;;EAID,IAAA,CAAA,EAAA;IAAA,MAAA,CAAA,EAAA,MAAA;IAAA,WAAA,CAAA,EAAA,OAAA;IAIH,YAAA,CAAA,EAAA,SAAA,MAAA,EAAA;IAAK,aAAA,CAAA,EAAA,SAAA,MAAA,EAAA;EAAA,CAAA;EAAA;;;;;EAIC,WAAA,CAAA,EAtL1B,YAsL0B;EAAA;;;;;;;;;;;;;;;;AAnHlB;;qBAhDH,uBAAuB;;;;;;;;;;WAUjC;;;;;;;;cAQG;;;;;;;;cAQA;;;;;;;;;;;;;;;;;cAmBA,8GAGA,WAAW;;;;;;eAEV;;;;;;;;;;;;;;;;;;mBAoBI;;;;;;;;;sBAUG;;uBAGC;kBAGhB,cAAc,gBACO,cAAc;0BAEC;;;;;;;;;;;;;;;;;;;sBAuDrB,wBAAwB;;kCAGZ,QAAK,gBAAA,oBAAA,uBAAA;mCAIJ,QAAK,gBAAA,oBAAA,wBAAA;kCAIN,QAAK,gBAAA,oBAAA,uBAAA;oCAIH,QAAK,gBAAA,oBAAA,yBAAA;qCAIJ,QAAK,gBAAA,oBAAA,0BAAA;sCAIJ,QAAK,gBAAA,oBAAA,2BAAA;;;;;;;;;;;;;;;kBAkBzB,aAAa,QAAQ,OAAO;;;;;;;;;;;;;;;6BAuBjB,eAAe,QAAQ,OAAO;;;;;;;;;;aAkB9C"}
+{"version":3,"file":"rest-api.d.mts","names":["_$__endpoints_EndpointFactory0.RemoveTrailingSlash","_$__endpoints0.EndpointBuilder"],"sources":["../src/rest-api.ts"],"mappings":";;;;;;;;iBAuCiB,cAIhB;;;;;;;;;;;;EAaA;;;;;;EAMA;IACC;IACA;IACA;IACA;;;;;;;EAOD,cAAc;;;;;;;;;;;;;;;;;;;EAmBd,mBAAmB,uBAAuB;;;;;;;;;;EAU1C,SAAS;;;;;;;;EAQT,YAAY;;;;;;;;EAQZ,YAAY;;;;;;;;;;;;;;;;;qBAmBA,QACZ,qCACM,iEACM,WAAW;mBAuCL;;mBAEA;;mBAEA;WAzCT,IAAI;;;;;;WAOJ;IACR;IACA;IACA;;;;;;;;;WAUQ,QAAQ;;;;;;;;;WAUR,WAAW;;WAGX,YAAY;EAGpB,YAAA,IAAI,cAAc,QACD,QAAQ,cAAc,eAEtB;;EAAA,wBAAuB,cAEvB;;EAAA;;;;;;;;;;;;;;;;;;WAqDT,WAAW,wBAAwB;;EAG5C,IAAI,sBAAsB,MAAM,QAAKC,gBAAAD,oBAAA,uBAAA,qFAAA,0BAAA,YAAA;EAIrC,KAAK,sBAAsB,MAAM,QAAKC,gBAAAD,oBAAA,wBAAA,qFAAA,0BAAA,YAAA;EAItC,IAAI,sBAAsB,MAAM,QAAKC,gBAAAD,oBAAA,uBAAA,qFAAA,0BAAA,YAAA;EAIrC,MAAM,sBAAsB,MAAM,QAAKC,gBAAAD,oBAAA,yBAAA,qFAAA,0BAAA,YAAA;EAIvC,OAAO,sBAAsB,MAAM,QAAKC,gBAAAD,oBAAA,0BAAA,qFAAA,0BAAA,YAAA;EAIxC,QAAQ,sBAAsB,MAAM,QAAKC,gBAAAD,oBAAA,2BAAA,qFAAA,0BAAA,YAAA;;;;;;;;;;;;;;;EAkBzC,KAAK,WAAW,aAAa,QAAQ,OAAO;;;;;;;;;;;;;;;EAuB5C,MAAM,qBAAqB,eAAe,QAAQ,OAAO;;;;;;;;;;EAkBzD,WAAW"}

package/dist/rest-api.mjs

@@ -1,13 +1,8 @@
-import "./Construct-BD5neF7w.mjs";
-import { edgeTo } from "./construct-interface-Z4CpS8tK.mjs";
-import "./functions-14lpEFL4.mjs";
-import { EndpointFactory } from "./EndpointFactory-CjV8F_lJ.mjs";
-import "./clone-DblgEZZa.mjs";
-import "./Endpoint-DCQPMdUX.mjs";
-import { envParserFor } from "./surfaceEnv-C3Ktahea.mjs";
+import { edgeTo } from "./construct-interface.mjs";
+import { t as EndpointFactory } from "./EndpointFactory-ptPR1cXw.mjs";
+import { n as envParserFor } from "./surfaceEnv-wMT5QzgZ.mjs";
 import { canonicalId, provideKey } from "@geekmidas/manifest";
 import { DEFAULT_LOGGER } from "@geekmidas/logger/console";
-
 //#region src/rest-api.ts
 /**
 * What is *not* here, and why.
@@ -25,6 +20,9 @@ import { DEFAULT_LOGGER } from "@geekmidas/logger/console";
 * What is left is what the *process* is rather than what a route may reach.
 */
 var RestApi = class RestApi {
+	config;
+	dependencies;
+	authenticator;
 	id;
 	/**
 	* Declared once and read by both `declare()` and anything that consumes this
@@ -178,7 +176,7 @@ var RestApi = class RestApi {
 		}];
 	}
 };
-
 //#endregion
 export { RestApi };
+
 //# sourceMappingURL=rest-api.mjs.map

package/dist/rest-api.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"rest-api.mjs","names":["id: ConstructName<TName>","config: RestApiConfig<TAuthorizers>","dependencies: readonly Dependency[]","authenticator?: string","path: TPath","construct: Declarable","constructs: readonly Declarable[]"],"sources":["../src/rest-api.ts"],"sourcesContent":["/**\n * `RestApi` — the application's own HTTP surface, declared.\n *\n * Everything an app serves already existed; what did not exist was a *node* for\n * it. Without one, three things that are properties of the graph had to be\n * written down somewhere else: which origins the API accepts, which origins the\n * auth server trusts, and which URL a frontend is built against. All three were\n * being derived by walking the workspace config for ports — a second mechanism,\n * running beside the graph and answering the same question worse, since it can\n * only ever describe what this repo happens to run.\n *\n * With the surface declared, all three become one edge read backwards: a\n * consumer depends on the API, and *that* is the CORS entry, the trusted origin,\n * and the build-time URL. Nothing enumerates its own callers.\n *\n * ```ts\n * export const api = new RestApi('Api', {\n *   authorizers: ['session'],\n *   defaultAuthorizer: 'session',\n * });\n * ```\n */\n\nimport type { EnvironmentParser } from '@geekmidas/envkit';\nimport type { Logger } from '@geekmidas/logger';\nimport { DEFAULT_LOGGER } from '@geekmidas/logger/console';\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\ttype Dependency,\n\tprovideKey,\n} from '@geekmidas/manifest';\nimport type { Telescope } from '@geekmidas/telescope';\nimport { type Declarable, edgeTo } from './construct-interface';\nimport type { BuiltInSecuritySchemeId } from './endpoints/Authorizer';\nimport { EndpointFactory } from './endpoints/EndpointFactory';\nimport { envParserFor } from './endpoints/surfaceEnv';\n\nexport interface RestApiConfig<\n\t// `readonly []` rather than `readonly string[]`: a surface that declares no\n\t// authorizers of its own should narrow `defaultAuthorizer` to the built-ins\n\t// and `'none'`, not widen it back to any string.\n\tTAuthorizers extends readonly string[] = readonly [],\n> {\n\t/**\n\t * The app that serves this surface, relative to the workspace root —\n\t * `'apps/api'`, or `'.'` in a single-app project.\n\t *\n\t * Required. It was inferred from the id (`apps/<kebab-id>`, or the root\n\t * when no such directory existed), which meant a surface's home was\n\t * whatever happened to be on disk. It is where the app's `package.json`\n\t * and base `tsconfig.json` are, and which build serves this surface. It\n\t * does not change discovery: constructs still load from the workspace's\n\t * `constructs` glob.\n\t */\n\tpath: string;\n\t/**\n\t * CORS tunables. The *origins* are never here — they are read off the\n\t * constructs that declared an edge to this surface, which is the whole point\n\t * of declaring one. These are the parts a graph cannot answer.\n\t */\n\tcors?: {\n\t\tmaxAge?: number;\n\t\tcredentials?: boolean;\n\t\tallowHeaders?: readonly string[];\n\t\texposeHeaders?: readonly string[];\n\t};\n\t/**\n\t * The authorizer names this surface exposes. Names only — what verifies a\n\t * request legitimately differs between local and deployed, so the mechanism\n\t * belongs to the target and never to portable code.\n\t */\n\tauthorizers?: TAuthorizers;\n\t/**\n\t * The authorizer applied to an endpoint that names none.\n\t *\n\t * Required, and `'none'` is a valid answer that has to be typed out. The\n\t * alternative is an API that ships open because a field was left off, which\n\t * is the one default worth refusing to have.\n\t *\n\t * It was called `default`, which said what it was to the type and nothing\n\t * to the reader: next to `authorizers: ['iam']`, a bare `default: 'none'`\n\t * could be defaulting the runtime or the target. The manifest has always\n\t * called it `defaultAuthorizer` and the factory `defaultAuthorizerName`;\n\t * this is the same fact under the same name.\n\t *\n\t * Typed from `authorizers`, so it can only name one this surface exposes —\n\t * plus a built-in scheme, and `'none'`. It was a bare `string`, which let\n\t * `defaultAuthorizer: 'jwtt'` compile and every endpoint on the surface\n\t * default to an authorizer that does not exist.\n\t */\n\tdefaultAuthorizer: TAuthorizers[number] | BuiltInSecuritySchemeId | 'none';\n\t/**\n\t * The logger every endpoint on this surface runs with.\n\t *\n\t * The actual logger, not a path to one. It used to be named in config as\n\t * `logger: './config/logger'`, because the build wrote an import into each\n\t * generated handler and a generator can print a specifier but not an object.\n\t * Endpoints built from the surface carry it, so there is nothing to print\n\t * and nothing to keep in step with a moved file.\n\t */\n\tlogger?: Logger;\n\t/**\n\t * The environment parser every endpoint on this surface runs with.\n\t *\n\t * Same reason as `logger`, and the same field it replaces —\n\t * `envParser: './config/env#envParser'`, a module path with an export name\n\t * appended, parsed by us, checked by nothing.\n\t */\n\tenvParser?: EnvironmentParser<{}>;\n\t/**\n\t * The Telescope instance this surface's entry mounts.\n\t *\n\t * The actual instance, for the reason `logger` is: it used to be named as\n\t * `telescope: './config/telescope#telescope'`, a module path the build\n\t * printed an import for. The entry already imports the surface.\n\t */\n\ttelescope?: Telescope;\n}\n\n/**\n * What is *not* here, and why.\n *\n * `dependsOn`, `database`, `auditor` and `publisher` all inject a capability\n * into a handler. Putting one on the surface hands it to every route the\n * surface serves — a health check gets the database because a report needed it\n * — which is the thing least privilege forbids and the reason `.calls()` is not\n * spelled `dependsOn`. They belong to the endpoint, or to a factory branched\n * from `api.endpoints` for a group of endpoints that genuinely share them.\n *\n * `auth` is not here either: `.auth(construct)` already declares it, and a\n * second way to say the same thing is the duplication this whole model removes.\n *\n * What is left is what the *process* is rather than what a route may reach.\n */\n\nexport class RestApi<\n\tTName extends string = string,\n\tconst TAuthorizers extends readonly string[] = readonly [],\n> implements Declarable<TName>\n{\n\treadonly id: TName;\n\n\t/**\n\t * Declared once and read by both `declare()` and anything that consumes this\n\t * surface, so what the target publishes and what a consumer reads cannot\n\t * drift.\n\t */\n\treadonly keys: {\n\t\turl: string;\n\t\ttrustedOrigins: string;\n\t\tcookieDomain: string;\n\t};\n\n\t/**\n\t * The logger every endpoint on this surface runs with.\n\t *\n\t * Always defined — the surface's own if it was given one, the console\n\t * logger otherwise — so nothing downstream has to decide what to do about a\n\t * missing one. The generated entry reads it from here.\n\t */\n\treadonly logger: Logger;\n\n\t/**\n\t * The environment parser every endpoint on this surface runs with.\n\t *\n\t * Always defined, and normally the default: `process.env` merged with the\n\t * credentials `gkm dev`/`gkm exec` injected. That is what every\n\t * application's own `config/env.ts` was — boilerplate identical in every\n\t * project, and mandatory, which is a poor combination.\n\t */\n\treadonly envParser: EnvironmentParser<{}>;\n\n\t/** The Telescope instance, when this surface was given one. */\n\treadonly telescope?: Telescope;\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly config: RestApiConfig<TAuthorizers>,\n\t\t/** Internal: how `.calls()` carries edges into the copy it returns. */\n\t\tprivate readonly dependencies: readonly Dependency[] = [],\n\t\t/** Internal: how `.auth()` carries the authenticator into its copy. */\n\t\tprivate readonly authenticator?: string,\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\n\t\tthis.keys = {\n\t\t\turl: provideKey(canonical, 'url'),\n\t\t\ttrustedOrigins: provideKey(canonical, 'trustedOrigins'),\n\t\t\tcookieDomain: provideKey(canonical, 'cookieDomain'),\n\t\t};\n\n\t\tthis.logger = config.logger ?? DEFAULT_LOGGER;\n\t\tthis.telescope = config.telescope;\n\t\tthis.envParser = envParserFor(\n\t\t\tconfig.envParser\n\t\t\t\t? { id: canonical, envParser: config.envParser }\n\t\t\t\t: undefined,\n\t\t);\n\n\t\tthis.endpoints = new EndpointFactory({\n\t\t\tdefaultLogger: this.logger,\n\t\t\t...(config.authorizers\n\t\t\t\t? {\n\t\t\t\t\t\tavailableAuthorizers: config.authorizers.map((name) => ({ name })),\n\t\t\t\t\t}\n\t\t\t\t: {}),\n\t\t\t// `'none'` reaches the factory as no default at all, which is what\n\t\t\t// public means to an endpoint that names no authorizer.\n\t\t\t...(config.defaultAuthorizer && config.defaultAuthorizer !== 'none'\n\t\t\t\t? { defaultAuthorizerName: config.defaultAuthorizer }\n\t\t\t\t: {}),\n\t\t\tsurface: { id: this.id, envParser: this.envParser },\n\t\t});\n\t}\n\n\t/**\n\t * This surface's endpoint factory.\n\t *\n\t * `api.get('/users')` is the short form and covers most routes. Reach for\n\t * this one when a *group* of endpoints shares something a single route would\n\t * otherwise repeat — a database, an auditor, a publisher:\n\t *\n\t * ```ts\n\t * const audited = api.endpoints.database(db).auditor(AuditStore);\n\t * export const createUser = audited.post('/users').handle(...);\n\t * ```\n\t *\n\t * A factory branched from here keeps the surface, so its endpoints still\n\t * know which API serves them. That is deliberately narrower than putting the\n\t * same thing in the surface's own config: a group opts in, where a surface\n\t * would grant it to every route it serves.\n\t */\n\treadonly endpoints: EndpointFactory<[], '', Logger>;\n\n\t/** `api.get('/users')` — sugar for `api.endpoints.get('/users')`. */\n\tget<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.get(path);\n\t}\n\n\tpost<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.post(path);\n\t}\n\n\tput<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.put(path);\n\t}\n\n\tpatch<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.patch(path);\n\t}\n\n\tdelete<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.delete(path);\n\t}\n\n\toptions<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.options(path);\n\t}\n\n\t/**\n\t * What authenticates this surface.\n\t *\n\t * An edge like `.calls()` — the auth server learns this origin, and the two\n\t * share a cookie domain — but a named one, because *who authenticates me* is\n\t * a different fact from *who I happen to call*, and only one of them decides\n\t * what a request is allowed to be. A surface with two of the first is a\n\t * mistake; two of the second is Tuesday.\n\t *\n\t * It records the id, not a client. Every endpoint consumes the same thing —\n\t * `verify(request) → Session | null` — and that is what every provider\n\t * shares, whether the server is mounted in this process, deployed beside it,\n\t * or an OIDC issuer somebody else runs.\n\t */\n\tauth(construct: Declarable): RestApi<TName, TAuthorizers> {\n\t\treturn new RestApi<TName, TAuthorizers>(\n\t\t\tthis.id as ConstructName<TName>,\n\t\t\tthis.config,\n\t\t\t[...this.dependencies, edgeTo(construct)],\n\t\t\tconstruct.id,\n\t\t);\n\t}\n\n\t/**\n\t * Other surfaces this one calls.\n\t *\n\t * **Not `.dependsOn()`, and the difference matters.** An endpoint's\n\t * `.dependsOn()` injects a client into that handler and grants it exactly\n\t * what it named. This grants nothing and injects nothing: it records that\n\t * this API calls another surface, which is what puts this API's origin on\n\t * that surface's trusted-origin list.\n\t *\n\t * Spelling it `dependsOn` would invite the thing least privilege forbids —\n\t * every route on the surface receiving whatever the surface named.\n\t *\n\t * Immutable, like every other builder here.\n\t */\n\tcalls(constructs: readonly Declarable[]): RestApi<TName, TAuthorizers> {\n\t\treturn new RestApi<TName, TAuthorizers>(\n\t\t\tthis.id as ConstructName<TName>,\n\t\t\tthis.config,\n\t\t\t[...this.dependencies, ...constructs.map(edgeTo)],\n\t\t\tthis.authenticator,\n\t\t);\n\t}\n\n\t/**\n\t * One surface node, with its endpoints left to the build.\n\t *\n\t * The three provided keys are one fact about this surface and two about its\n\t * callers. Declaring the caller-derived pair here rather than having the\n\t * target invent them is what makes the contract checkable: a target that\n\t * resolves no origins is caught against this list instead of being noticed\n\t * when a browser is refused in production.\n\t */\n\tdeclare(): Declaration[] {\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'rest-api',\n\t\t\t\tid: this.id,\n\t\t\t\tpath: this.config.path,\n\t\t\t\t...(this.config.telescope ? { telescope: true } : {}),\n\t\t\t\t...(this.config.cors ? { cors: this.config.cors } : {}),\n\t\t\t\t...(this.authenticator ? { auth: this.authenticator } : {}),\n\t\t\t\t// Filled by the build, which already generates one handler per\n\t\t\t\t// endpoint and knows the path it wrote it to. A surface that\n\t\t\t\t// enumerates its own routes statically — an auth server's single\n\t\t\t\t// wildcard — puts them here instead.\n\t\t\t\tendpoints: [],\n\t\t\t\t...(this.dependencies.length ? { calls: this.dependencies } : {}),\n\t\t\t\t...(this.config.authorizers?.length\n\t\t\t\t\t? { authorizers: this.config.authorizers }\n\t\t\t\t\t: {}),\n\t\t\t\tdefaultAuthorizer: this.config.defaultAuthorizer,\n\t\t\t\tprovides: [\n\t\t\t\t\tthis.keys.url,\n\t\t\t\t\tthis.keys.trustedOrigins,\n\t\t\t\t\tthis.keys.cookieDomain,\n\t\t\t\t],\n\t\t\t},\n\t\t];\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAyIA,IAAa,UAAb,MAAa,QAIb;CACC,AAAS;;;;;;CAOT,AAAS;;;;;;;;CAaT,AAAS;;;;;;;;;CAUT,AAAS;;CAGT,AAAS;CAET,YACCA,IACiBC,QAEAC,eAAsC,CAAE,GAExCC,eAChB;EALgB;EAEA;EAEA;EAEjB,MAAM,YAAY,YAAY,GAAa;AAE3C,OAAK,KAAK;AAEV,OAAK,OAAO;GACX,KAAK,WAAW,WAAW,MAAM;GACjC,gBAAgB,WAAW,WAAW,iBAAiB;GACvD,cAAc,WAAW,WAAW,eAAe;EACnD;AAED,OAAK,SAAS,OAAO,UAAU;AAC/B,OAAK,YAAY,OAAO;AACxB,OAAK,YAAY,aAChB,OAAO,YACJ;GAAE,IAAI;GAAW,WAAW,OAAO;EAAW,WAEjD;AAED,OAAK,YAAY,IAAI,gBAAgB;GACpC,eAAe,KAAK;GACpB,GAAI,OAAO,cACR,EACA,sBAAsB,OAAO,YAAY,IAAI,CAAC,UAAU,EAAE,KAAM,GAAE,CAClE,IACA,CAAE;GAGL,GAAI,OAAO,qBAAqB,OAAO,sBAAsB,SAC1D,EAAE,uBAAuB,OAAO,kBAAmB,IACnD,CAAE;GACL,SAAS;IAAE,IAAI,KAAK;IAAI,WAAW,KAAK;GAAW;EACnD;CACD;;;;;;;;;;;;;;;;;;CAmBD,AAAS;;CAGT,IAA0BC,MAAa;AACtC,SAAO,KAAK,UAAU,IAAI,KAAK;CAC/B;CAED,KAA2BA,MAAa;AACvC,SAAO,KAAK,UAAU,KAAK,KAAK;CAChC;CAED,IAA0BA,MAAa;AACtC,SAAO,KAAK,UAAU,IAAI,KAAK;CAC/B;CAED,MAA4BA,MAAa;AACxC,SAAO,KAAK,UAAU,MAAM,KAAK;CACjC;CAED,OAA6BA,MAAa;AACzC,SAAO,KAAK,UAAU,OAAO,KAAK;CAClC;CAED,QAA8BA,MAAa;AAC1C,SAAO,KAAK,UAAU,QAAQ,KAAK;CACnC;;;;;;;;;;;;;;;CAgBD,KAAKC,WAAqD;AACzD,SAAO,IAAI,QACV,KAAK,IACL,KAAK,QACL,CAAC,GAAG,KAAK,cAAc,OAAO,UAAU,AAAC,GACzC,UAAU;CAEX;;;;;;;;;;;;;;;CAgBD,MAAMC,YAAiE;AACtE,SAAO,IAAI,QACV,KAAK,IACL,KAAK,QACL,CAAC,GAAG,KAAK,cAAc,GAAG,WAAW,IAAI,OAAO,AAAC,GACjD,KAAK;CAEN;;;;;;;;;;CAWD,UAAyB;AACxB,SAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,MAAM,KAAK,OAAO;GAClB,GAAI,KAAK,OAAO,YAAY,EAAE,WAAW,KAAM,IAAG,CAAE;GACpD,GAAI,KAAK,OAAO,OAAO,EAAE,MAAM,KAAK,OAAO,KAAM,IAAG,CAAE;GACtD,GAAI,KAAK,gBAAgB,EAAE,MAAM,KAAK,cAAe,IAAG,CAAE;GAK1D,WAAW,CAAE;GACb,GAAI,KAAK,aAAa,SAAS,EAAE,OAAO,KAAK,aAAc,IAAG,CAAE;GAChE,GAAI,KAAK,OAAO,aAAa,SAC1B,EAAE,aAAa,KAAK,OAAO,YAAa,IACxC,CAAE;GACL,mBAAmB,KAAK,OAAO;GAC/B,UAAU;IACT,KAAK,KAAK;IACV,KAAK,KAAK;IACV,KAAK,KAAK;GACV;EACD,CACD;CACD;AACD"}
+{"version":3,"file":"rest-api.mjs","names":[],"sources":["../src/rest-api.ts"],"sourcesContent":["/**\n * `RestApi` — the application's own HTTP surface, declared.\n *\n * Everything an app serves already existed; what did not exist was a *node* for\n * it. Without one, three things that are properties of the graph had to be\n * written down somewhere else: which origins the API accepts, which origins the\n * auth server trusts, and which URL a frontend is built against. All three were\n * being derived by walking the workspace config for ports — a second mechanism,\n * running beside the graph and answering the same question worse, since it can\n * only ever describe what this repo happens to run.\n *\n * With the surface declared, all three become one edge read backwards: a\n * consumer depends on the API, and *that* is the CORS entry, the trusted origin,\n * and the build-time URL. Nothing enumerates its own callers.\n *\n * ```ts\n * export const api = new RestApi('Api', {\n *   authorizers: ['session'],\n *   defaultAuthorizer: 'session',\n * });\n * ```\n */\n\nimport type { EnvironmentParser } from '@geekmidas/envkit';\nimport type { Logger } from '@geekmidas/logger';\nimport { DEFAULT_LOGGER } from '@geekmidas/logger/console';\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\ttype Dependency,\n\tprovideKey,\n} from '@geekmidas/manifest';\nimport type { Telescope } from '@geekmidas/telescope';\nimport { type Declarable, edgeTo } from './construct-interface';\nimport type { BuiltInSecuritySchemeId } from './endpoints/Authorizer';\nimport { EndpointFactory } from './endpoints/EndpointFactory';\nimport { envParserFor } from './endpoints/surfaceEnv';\n\nexport interface RestApiConfig<\n\t// `readonly []` rather than `readonly string[]`: a surface that declares no\n\t// authorizers of its own should narrow `defaultAuthorizer` to the built-ins\n\t// and `'none'`, not widen it back to any string.\n\tTAuthorizers extends readonly string[] = readonly [],\n> {\n\t/**\n\t * The app that serves this surface, relative to the workspace root —\n\t * `'apps/api'`, or `'.'` in a single-app project.\n\t *\n\t * Required. It was inferred from the id (`apps/<kebab-id>`, or the root\n\t * when no such directory existed), which meant a surface's home was\n\t * whatever happened to be on disk. It is where the app's `package.json`\n\t * and base `tsconfig.json` are, and which build serves this surface. It\n\t * does not change discovery: constructs still load from the workspace's\n\t * `constructs` glob.\n\t */\n\tpath: string;\n\t/**\n\t * CORS tunables. The *origins* are never here — they are read off the\n\t * constructs that declared an edge to this surface, which is the whole point\n\t * of declaring one. These are the parts a graph cannot answer.\n\t */\n\tcors?: {\n\t\tmaxAge?: number;\n\t\tcredentials?: boolean;\n\t\tallowHeaders?: readonly string[];\n\t\texposeHeaders?: readonly string[];\n\t};\n\t/**\n\t * The authorizer names this surface exposes. Names only — what verifies a\n\t * request legitimately differs between local and deployed, so the mechanism\n\t * belongs to the target and never to portable code.\n\t */\n\tauthorizers?: TAuthorizers;\n\t/**\n\t * The authorizer applied to an endpoint that names none.\n\t *\n\t * Required, and `'none'` is a valid answer that has to be typed out. The\n\t * alternative is an API that ships open because a field was left off, which\n\t * is the one default worth refusing to have.\n\t *\n\t * It was called `default`, which said what it was to the type and nothing\n\t * to the reader: next to `authorizers: ['iam']`, a bare `default: 'none'`\n\t * could be defaulting the runtime or the target. The manifest has always\n\t * called it `defaultAuthorizer` and the factory `defaultAuthorizerName`;\n\t * this is the same fact under the same name.\n\t *\n\t * Typed from `authorizers`, so it can only name one this surface exposes —\n\t * plus a built-in scheme, and `'none'`. It was a bare `string`, which let\n\t * `defaultAuthorizer: 'jwtt'` compile and every endpoint on the surface\n\t * default to an authorizer that does not exist.\n\t */\n\tdefaultAuthorizer: TAuthorizers[number] | BuiltInSecuritySchemeId | 'none';\n\t/**\n\t * The logger every endpoint on this surface runs with.\n\t *\n\t * The actual logger, not a path to one. It used to be named in config as\n\t * `logger: './config/logger'`, because the build wrote an import into each\n\t * generated handler and a generator can print a specifier but not an object.\n\t * Endpoints built from the surface carry it, so there is nothing to print\n\t * and nothing to keep in step with a moved file.\n\t */\n\tlogger?: Logger;\n\t/**\n\t * The environment parser every endpoint on this surface runs with.\n\t *\n\t * Same reason as `logger`, and the same field it replaces —\n\t * `envParser: './config/env#envParser'`, a module path with an export name\n\t * appended, parsed by us, checked by nothing.\n\t */\n\tenvParser?: EnvironmentParser<{}>;\n\t/**\n\t * The Telescope instance this surface's entry mounts.\n\t *\n\t * The actual instance, for the reason `logger` is: it used to be named as\n\t * `telescope: './config/telescope#telescope'`, a module path the build\n\t * printed an import for. The entry already imports the surface.\n\t */\n\ttelescope?: Telescope;\n}\n\n/**\n * What is *not* here, and why.\n *\n * `dependsOn`, `database`, `auditor` and `publisher` all inject a capability\n * into a handler. Putting one on the surface hands it to every route the\n * surface serves — a health check gets the database because a report needed it\n * — which is the thing least privilege forbids and the reason `.calls()` is not\n * spelled `dependsOn`. They belong to the endpoint, or to a factory branched\n * from `api.endpoints` for a group of endpoints that genuinely share them.\n *\n * `auth` is not here either: `.auth(construct)` already declares it, and a\n * second way to say the same thing is the duplication this whole model removes.\n *\n * What is left is what the *process* is rather than what a route may reach.\n */\n\nexport class RestApi<\n\tTName extends string = string,\n\tconst TAuthorizers extends readonly string[] = readonly [],\n> implements Declarable<TName>\n{\n\treadonly id: TName;\n\n\t/**\n\t * Declared once and read by both `declare()` and anything that consumes this\n\t * surface, so what the target publishes and what a consumer reads cannot\n\t * drift.\n\t */\n\treadonly keys: {\n\t\turl: string;\n\t\ttrustedOrigins: string;\n\t\tcookieDomain: string;\n\t};\n\n\t/**\n\t * The logger every endpoint on this surface runs with.\n\t *\n\t * Always defined — the surface's own if it was given one, the console\n\t * logger otherwise — so nothing downstream has to decide what to do about a\n\t * missing one. The generated entry reads it from here.\n\t */\n\treadonly logger: Logger;\n\n\t/**\n\t * The environment parser every endpoint on this surface runs with.\n\t *\n\t * Always defined, and normally the default: `process.env` merged with the\n\t * credentials `gkm dev`/`gkm exec` injected. That is what every\n\t * application's own `config/env.ts` was — boilerplate identical in every\n\t * project, and mandatory, which is a poor combination.\n\t */\n\treadonly envParser: EnvironmentParser<{}>;\n\n\t/** The Telescope instance, when this surface was given one. */\n\treadonly telescope?: Telescope;\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly config: RestApiConfig<TAuthorizers>,\n\t\t/** Internal: how `.calls()` carries edges into the copy it returns. */\n\t\tprivate readonly dependencies: readonly Dependency[] = [],\n\t\t/** Internal: how `.auth()` carries the authenticator into its copy. */\n\t\tprivate readonly authenticator?: string,\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\n\t\tthis.keys = {\n\t\t\turl: provideKey(canonical, 'url'),\n\t\t\ttrustedOrigins: provideKey(canonical, 'trustedOrigins'),\n\t\t\tcookieDomain: provideKey(canonical, 'cookieDomain'),\n\t\t};\n\n\t\tthis.logger = config.logger ?? DEFAULT_LOGGER;\n\t\tthis.telescope = config.telescope;\n\t\tthis.envParser = envParserFor(\n\t\t\tconfig.envParser\n\t\t\t\t? { id: canonical, envParser: config.envParser }\n\t\t\t\t: undefined,\n\t\t);\n\n\t\tthis.endpoints = new EndpointFactory({\n\t\t\tdefaultLogger: this.logger,\n\t\t\t...(config.authorizers\n\t\t\t\t? {\n\t\t\t\t\t\tavailableAuthorizers: config.authorizers.map((name) => ({ name })),\n\t\t\t\t\t}\n\t\t\t\t: {}),\n\t\t\t// `'none'` reaches the factory as no default at all, which is what\n\t\t\t// public means to an endpoint that names no authorizer.\n\t\t\t...(config.defaultAuthorizer && config.defaultAuthorizer !== 'none'\n\t\t\t\t? { defaultAuthorizerName: config.defaultAuthorizer }\n\t\t\t\t: {}),\n\t\t\tsurface: { id: this.id, envParser: this.envParser },\n\t\t});\n\t}\n\n\t/**\n\t * This surface's endpoint factory.\n\t *\n\t * `api.get('/users')` is the short form and covers most routes. Reach for\n\t * this one when a *group* of endpoints shares something a single route would\n\t * otherwise repeat — a database, an auditor, a publisher:\n\t *\n\t * ```ts\n\t * const audited = api.endpoints.database(db).auditor(AuditStore);\n\t * export const createUser = audited.post('/users').handle(...);\n\t * ```\n\t *\n\t * A factory branched from here keeps the surface, so its endpoints still\n\t * know which API serves them. That is deliberately narrower than putting the\n\t * same thing in the surface's own config: a group opts in, where a surface\n\t * would grant it to every route it serves.\n\t */\n\treadonly endpoints: EndpointFactory<[], '', Logger>;\n\n\t/** `api.get('/users')` — sugar for `api.endpoints.get('/users')`. */\n\tget<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.get(path);\n\t}\n\n\tpost<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.post(path);\n\t}\n\n\tput<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.put(path);\n\t}\n\n\tpatch<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.patch(path);\n\t}\n\n\tdelete<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.delete(path);\n\t}\n\n\toptions<TPath extends string>(path: TPath) {\n\t\treturn this.endpoints.options(path);\n\t}\n\n\t/**\n\t * What authenticates this surface.\n\t *\n\t * An edge like `.calls()` — the auth server learns this origin, and the two\n\t * share a cookie domain — but a named one, because *who authenticates me* is\n\t * a different fact from *who I happen to call*, and only one of them decides\n\t * what a request is allowed to be. A surface with two of the first is a\n\t * mistake; two of the second is Tuesday.\n\t *\n\t * It records the id, not a client. Every endpoint consumes the same thing —\n\t * `verify(request) → Session | null` — and that is what every provider\n\t * shares, whether the server is mounted in this process, deployed beside it,\n\t * or an OIDC issuer somebody else runs.\n\t */\n\tauth(construct: Declarable): RestApi<TName, TAuthorizers> {\n\t\treturn new RestApi<TName, TAuthorizers>(\n\t\t\tthis.id as ConstructName<TName>,\n\t\t\tthis.config,\n\t\t\t[...this.dependencies, edgeTo(construct)],\n\t\t\tconstruct.id,\n\t\t);\n\t}\n\n\t/**\n\t * Other surfaces this one calls.\n\t *\n\t * **Not `.dependsOn()`, and the difference matters.** An endpoint's\n\t * `.dependsOn()` injects a client into that handler and grants it exactly\n\t * what it named. This grants nothing and injects nothing: it records that\n\t * this API calls another surface, which is what puts this API's origin on\n\t * that surface's trusted-origin list.\n\t *\n\t * Spelling it `dependsOn` would invite the thing least privilege forbids —\n\t * every route on the surface receiving whatever the surface named.\n\t *\n\t * Immutable, like every other builder here.\n\t */\n\tcalls(constructs: readonly Declarable[]): RestApi<TName, TAuthorizers> {\n\t\treturn new RestApi<TName, TAuthorizers>(\n\t\t\tthis.id as ConstructName<TName>,\n\t\t\tthis.config,\n\t\t\t[...this.dependencies, ...constructs.map(edgeTo)],\n\t\t\tthis.authenticator,\n\t\t);\n\t}\n\n\t/**\n\t * One surface node, with its endpoints left to the build.\n\t *\n\t * The three provided keys are one fact about this surface and two about its\n\t * callers. Declaring the caller-derived pair here rather than having the\n\t * target invent them is what makes the contract checkable: a target that\n\t * resolves no origins is caught against this list instead of being noticed\n\t * when a browser is refused in production.\n\t */\n\tdeclare(): Declaration[] {\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'rest-api',\n\t\t\t\tid: this.id,\n\t\t\t\tpath: this.config.path,\n\t\t\t\t...(this.config.telescope ? { telescope: true } : {}),\n\t\t\t\t...(this.config.cors ? { cors: this.config.cors } : {}),\n\t\t\t\t...(this.authenticator ? { auth: this.authenticator } : {}),\n\t\t\t\t// Filled by the build, which already generates one handler per\n\t\t\t\t// endpoint and knows the path it wrote it to. A surface that\n\t\t\t\t// enumerates its own routes statically — an auth server's single\n\t\t\t\t// wildcard — puts them here instead.\n\t\t\t\tendpoints: [],\n\t\t\t\t...(this.dependencies.length ? { calls: this.dependencies } : {}),\n\t\t\t\t...(this.config.authorizers?.length\n\t\t\t\t\t? { authorizers: this.config.authorizers }\n\t\t\t\t\t: {}),\n\t\t\t\tdefaultAuthorizer: this.config.defaultAuthorizer,\n\t\t\t\tprovides: [\n\t\t\t\t\tthis.keys.url,\n\t\t\t\t\tthis.keys.trustedOrigins,\n\t\t\t\t\tthis.keys.cookieDomain,\n\t\t\t\t],\n\t\t\t},\n\t\t];\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAyIA,IAAa,UAAb,MAAa,QAIb;CAsCmB;CAEA;CAEA;CAzClB;;;;;;CAOA;;;;;;;;CAaA;;;;;;;;;CAUA;;CAGA;CAEA,YACC,IACA,QAEA,eAAuD,CAAC,GAExD,eACC;EALgB,KAAA,SAAA;EAEA,KAAA,eAAA;EAEA,KAAA,gBAAA;EAEjB,MAAM,YAAY,YAAY,EAAY;EAE1C,KAAK,KAAK;EAEV,KAAK,OAAO;GACX,KAAK,WAAW,WAAW,KAAK;GAChC,gBAAgB,WAAW,WAAW,gBAAgB;GACtD,cAAc,WAAW,WAAW,cAAc;EACnD;EAEA,KAAK,SAAS,OAAO,UAAU;EAC/B,KAAK,YAAY,OAAO;EACxB,KAAK,YAAY,aAChB,OAAO,YACJ;GAAE,IAAI;GAAW,WAAW,OAAO;EAAU,IAC7C,KAAA,CACJ;EAEA,KAAK,YAAY,IAAI,gBAAgB;GACpC,eAAe,KAAK;GACpB,GAAI,OAAO,cACR,EACA,sBAAsB,OAAO,YAAY,KAAK,UAAU,EAAE,KAAK,EAAE,EAClE,IACC,CAAC;GAGJ,GAAI,OAAO,qBAAqB,OAAO,sBAAsB,SAC1D,EAAE,uBAAuB,OAAO,kBAAkB,IAClD,CAAC;GACJ,SAAS;IAAE,IAAI,KAAK;IAAI,WAAW,KAAK;GAAU;EACnD,CAAC;CACF;;;;;;;;;;;;;;;;;;CAmBA;;CAGA,IAA0B,MAAa;EACtC,OAAO,KAAK,UAAU,IAAI,IAAI;CAC/B;CAEA,KAA2B,MAAa;EACvC,OAAO,KAAK,UAAU,KAAK,IAAI;CAChC;CAEA,IAA0B,MAAa;EACtC,OAAO,KAAK,UAAU,IAAI,IAAI;CAC/B;CAEA,MAA4B,MAAa;EACxC,OAAO,KAAK,UAAU,MAAM,IAAI;CACjC;CAEA,OAA6B,MAAa;EACzC,OAAO,KAAK,UAAU,OAAO,IAAI;CAClC;CAEA,QAA8B,MAAa;EAC1C,OAAO,KAAK,UAAU,QAAQ,IAAI;CACnC;;;;;;;;;;;;;;;CAgBA,KAAK,WAAqD;EACzD,OAAO,IAAI,QACV,KAAK,IACL,KAAK,QACL,CAAC,GAAG,KAAK,cAAc,OAAO,SAAS,CAAC,GACxC,UAAU,EACX;CACD;;;;;;;;;;;;;;;CAgBA,MAAM,YAAiE;EACtE,OAAO,IAAI,QACV,KAAK,IACL,KAAK,QACL,CAAC,GAAG,KAAK,cAAc,GAAG,WAAW,IAAI,MAAM,CAAC,GAChD,KAAK,aACN;CACD;;;;;;;;;;CAWA,UAAyB;EACxB,OAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,MAAM,KAAK,OAAO;GAClB,GAAI,KAAK,OAAO,YAAY,EAAE,WAAW,KAAK,IAAI,CAAC;GACnD,GAAI,KAAK,OAAO,OAAO,EAAE,MAAM,KAAK,OAAO,KAAK,IAAI,CAAC;GACrD,GAAI,KAAK,gBAAgB,EAAE,MAAM,KAAK,cAAc,IAAI,CAAC;GAKzD,WAAW,CAAC;GACZ,GAAI,KAAK,aAAa,SAAS,EAAE,OAAO,KAAK,aAAa,IAAI,CAAC;GAC/D,GAAI,KAAK,OAAO,aAAa,SAC1B,EAAE,aAAa,KAAK,OAAO,YAAY,IACvC,CAAC;GACJ,mBAAmB,KAAK,OAAO;GAC/B,UAAU;IACT,KAAK,KAAK;IACV,KAAK,KAAK;IACV,KAAK,KAAK;GACX;EACD,CACD;CACD;AACD"}

package/dist/{chunk-DWy1uDak.cjs → rolldown-runtime-y5ARvAq5.cjs}

@@ -1,13 +1,11 @@
-//#region rolldown:runtime
+//#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __commonJS = (cb, mod) => function() {
-	return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
-};
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 var __copyProps = (to, from, except, desc) => {
 	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
 		key = keys[i];
@@ -18,22 +16,20 @@ var __copyProps = (to, from, except, desc) => {
 	}
 	return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
 	value: mod,
 	enumerable: true
 }) : target, mod));
-
 //#endregion
-
-Object.defineProperty(exports, '__commonJS', {
-  enumerable: true,
-  get: function () {
-    return __commonJS;
-  }
+Object.defineProperty(exports, "__commonJSMin", {
+	enumerable: true,
+	get: function() {
+		return __commonJSMin;
+	}
+});
+Object.defineProperty(exports, "__toESM", {
+	enumerable: true,
+	get: function() {
+		return __toESM;
+	}
 });
-Object.defineProperty(exports, '__toESM', {
-  enumerable: true,
-  get: function () {
-    return __toESM;
-  }
-});