@fabrika/app 0.5.5 → 0.7.0

package/src/contract/group.ts

@@ -2,15 +2,44 @@
 // handler with `.handle(fn)` beside it. `.handle` returns the declaration without the handler's type, so a contract
 // of many endpoints stays cheap to type-check, and an endpoint without `.handle` is not a group member.
 
-import type { RpcCaller } from '@fabrika/auth-core'
+import type { EndpointCache, RpcCaller } from '@fabrika/auth-core'
 import type { AnyDbIndex, ReadOnlyUnscoped, Unavailable, UnscopedDeclaration, UnscopedMode } from '@fabrika/db/tables'
 import type { z } from 'zod/v4'
 import type { Snake } from '../from-row'
 import type { ExtraKeys, HandlerInput, IsAny } from '../implement/types'
 import type { AttachmentBrand } from './attachment'
-import type { CheckedAccess, Declared, EndpointContext, ExportContext, ImportOf, KitTypes, LinkContext, SqlMode } from './context'
+import type {
+	CheckedAccess,
+	Declared,
+	EndpointContext,
+	ExportContext,
+	ImportOf,
+	KickContext,
+	KitTypes,
+	LinkContext,
+	PublicContext,
+	SqlMode,
+	TokensContext,
+	WebhooksContext,
+} from './context'
 import type { ProcedureType } from './declaration'
-import type { AppAccess, InputOf, InputSchema, LinkAccess, MemberAccess, MutationAccess, NotLoose, Procedure, QueryAccess, Schema } from './define'
+import type {
+	AppAccess,
+	CapabilitiesAccess,
+	CapabilityAccess,
+	ChallengeOption,
+	InputOf,
+	InputSchema,
+	LinkAccess,
+	MemberAccess,
+	MutationAccess,
+	NotLoose,
+	Procedure,
+	PublicAccess,
+	QueryAccess,
+	Schema,
+} from './define'
+import type { WithClaims } from './token'
 
 /** Fields a builder sets itself: a definition that carries one does not type-check. */
 type Owned<K extends string> = { readonly [P in K]?: never }
@@ -55,24 +84,105 @@ type OneLiteral<Is> = string extends Is ? Unavailable<"issues names one link mou
 	: true extends IsUnion<Is> ? Unavailable<"issues names one link mount, as a literal: issues: 'shared'">
 	: unknown
 
-/** `then` names one cron job, as a literal. */
-type OneJob<Th> = string extends Th ? Unavailable<"then names one cron job, as a literal: then: 'mailing'">
-	: true extends IsUnion<Th> ? Unavailable<"then names one cron job, as a literal: then: 'mailing'">
+/** A query writes nothing, so it has nothing to kick a job for and no binding to write. */
+type NoKick = {
+	readonly kicks?: Unavailable<'a query kicks no job: declare kicks on a mutation'>
+	readonly binds?: Unavailable<'a query binds no webhook: declare binds on a mutation'>
+}
+
+/** `binds` names one webhook, as a literal. */
+type OneWebhook<Bs> = string extends Bs ? Unavailable<"binds names one webhook, as a literal: binds: 'stripe'">
+	: true extends IsUnion<Bs> ? Unavailable<"binds names one webhook, as a literal: binds: 'stripe'">
 	: unknown
 
-/** A mutation's `then`, inferred from its optional field and then required, like a declared field. */
-type KickField<Th> =
-	& {
-		/** The cron job this mutation kicks once its transaction committed; the schedule stays its recovery. */
-		readonly then?: Th
-	}
-	& ([Th] extends [never] ? unknown : { readonly then: Th & NoInfer<OneJob<Th>> })
+/** The webhook whose bindings a mutation writes (`ctx.webhooks`), inferred from its optional field and then required. */
+type BindsField<Bs> =
+	& { readonly binds?: Bs }
+	& ([Bs] extends [never] ? unknown : { readonly binds: Bs & NoInfer<OneWebhook<Bs>> })
+
+/** The jobs a mutation may kick (`ctx.kick`), inferred from its optional field and then required, as a literal list. */
+export type KicksField<Ks> =
+	& { readonly kicks?: Ks }
+	& ([Ks] extends [never] ? unknown : { readonly kicks: Ks & NoInfer<LiteralList<Ks>> })
+
+/** The token purposes a site signs (`ctx.tokens.sign`), inferred from its optional field and then required, as a literal list. */
+export type SignsField<Sg, Purposes extends string> =
+	& { readonly signs?: Sg }
+	& ([Sg] extends [never] ? unknown : { readonly signs: Sg & NoInfer<KnownPurposes<Sg, Purposes>> })
+
+/**
+ * The HTTPS origins a site's code calls (`fetch`): each an exact origin, no path or wildcard. A guard on the global
+ * `fetch` refuses any other while the site runs; a public procedure declares none.
+ */
+export interface EgressField {
+	readonly egress?: readonly `https://${string}`[]
+}
 
-/** A query writes nothing, so it has nothing to kick a job for. */
-type NoKick = { readonly then?: Unavailable<'a query kicks no job: declare then on a mutation'> }
+/** Each purpose `signs` names is one of `defineApp`'s `tokens`. */
+type KnownPurposes<Sg, Purposes extends string> = Sg extends readonly (infer P extends string)[]
+	? [Exclude<P, Purposes>] extends [never] ? LiteralList<Sg>
+	: Unavailable<`signs names ${ListOf<Exclude<P, Purposes>>}, which defineApp's tokens do not declare`>
+	: unknown
 
 type IsUnion<T, All = T> = T extends unknown ? ([All] extends [T] ? false : true) : never
 
+/** A bucket's calls per minute, or `null` to turn a default bucket off. */
+type Bucket = number | null
+
+/**
+ * How a procedure is admitted (`admission`), merged into its kind's default: a public mutation counts 10 calls per
+ * minute per client and 100 for the endpoint; every other procedure counts none unless it declares a bucket.
+ */
+export type AdmissionOption<Acc> = [Acc] extends [PublicAccess] ? {
+		/** `'same-origin'` by default; `'listed'` the environment's listed origins; `'any'` every origin. */
+		readonly origins?: 'same-origin' | 'listed' | 'any'
+		readonly rate?: { readonly perClient?: Bucket; readonly perEndpoint?: Bucket; readonly bytesPerHour?: Bucket }
+		/** Verified on the server before the handler; the input carries the widget's token in `challengeToken`. */
+		readonly challenge?: ChallengeOption
+	}
+	: {
+		/** `'same-origin'` by default; `'listed'` the environment's listed origins, with a key only (ADR-0022). */
+		readonly origins?: 'same-origin' | 'listed'
+		readonly rate?: { readonly perCaller?: Bucket; readonly perEndpoint?: Bucket }
+	}
+
+/** A procedure's bounds: its body in bytes (64 KiB by default, at most 1 MiB) and its handler's time (10 s, at most 60 s). */
+export interface LimitsOption {
+	readonly maxBytes?: number
+	readonly timeoutMs?: number
+}
+
+/**
+ * A public procedure's workload actions, which its handler holds and nothing else; no other procedure declares them.
+ * Inferred from the optional field and then required, like a declared field.
+ */
+export type PublicFields<Acc, Acts> = [Acc] extends [PublicAccess] ? {
+		readonly actions:
+			& Acts
+			& NoInfer<Acts extends readonly [] ? Unavailable<"a public procedure names what its handler holds: actions: ['<action>']"> : unknown>
+	}
+	: { readonly actions?: Unavailable<'only a public procedure declares actions: its handler runs as its own workload'> }
+
+/** The handler context of a group's procedure: a public one runs as its own workload, every other as its caller. */
+export type ProcedureContext<
+	K extends KitTypes,
+	Caller extends RpcCaller,
+	Kind extends 'query' | 'mutation',
+	Acc,
+	Acts extends readonly string[],
+	D extends Declared<SqlMode, unknown, readonly string[], string>,
+	Ks = never,
+	Bs = never,
+	Sg = never,
+> =
+	& ([Acc] extends [PublicAccess] ? PublicContext<K, Kind, Acts[number]>
+		: EndpointContext<K, Caller, Kind, CheckedAccess<Acc>, D> & WebhooksContext<Bs>)
+	& KickContext<Ks>
+	& TokensContext<K, Sg>
+
+/** A group without callers holds public procedures only; any other group may hold both. */
+export type GroupAccess<Caller extends RpcCaller, Acc> = [Caller] extends [never] ? PublicAccess : Acc | PublicAccess
+
 /** An endpoint's declaration: its schemas, its access form and the reach it declares. */
 export type EndpointDef<I, O, Acc, S, U, Cn, Is, Ix extends AnyDbIndex> =
 	& Owned<'~kind' | 'type'>
@@ -80,11 +190,23 @@ export type EndpointDef<I, O, Acc, S, U, Cn, Is, Ix extends AnyDbIndex> =
 		readonly input?: I & NotLoose<I>
 		readonly output: O & NotLoose<O>
 		readonly access: Acc
-		/** A page on one of the environment's listed origins may call it, with a key (ADR-0022). An RPC endpoint only. */
-		readonly crossOrigin?: true
+		readonly admission?: AdmissionOption<Acc>
+		readonly limits?: LimitsOption
 	}
 	& DeclaredFields<S, U, Cn, Is, Ix>
 
+/**
+ * A group procedure's HTTP shape, its `query` schema inferred: what its handler then reads as `query`. Only a public
+ * procedure has a path of its own.
+ */
+type HttpField<Q, Acc> = { readonly http?: HttpOption<Q & NoInfer<NotLoose<Q>>> & OwnPathOption<Acc> }
+
+/**
+ * `http.path`: a public procedure served at a literal path of its own instead of `<prefix>/<name>`, so a caller outside
+ * the application keeps its URL. It lies outside every mount's prefix and under no `/__fabrika`.
+ */
+export type OwnPathOption<Acc> = [Acc] extends [PublicAccess] ? { readonly path?: `/${string}` } : unknown
+
 type Returned<F> = F extends (args: never) => infer R ? Awaited<R> : never
 
 /** The last member of a union, in the order the compiler holds it. */
@@ -120,8 +242,31 @@ export type HandlerReturn<F, O extends Schema> = [Returned<F>] extends [z.input<
 	: [Returned<F>] extends [RowShaped<z.input<O>>] ? RowShaped<z.input<O>>
 	: z.input<O>
 
-/** A kit endpoint's handler, returning `R`. */
-export type KitHandler<In, Ctx, R> = (args: { readonly input: In; readonly ctx: Ctx }) => R | Promise<R>
+/** A kit endpoint's handler, returning `R`; `X` adds what its HTTP shape reads beside the input (`query`). */
+export type KitHandler<In, Ctx, R, X = unknown> = (args: { readonly input: In; readonly ctx: Ctx } & X) => R | Promise<R>
+
+/**
+ * What a handler reads beside its input: the URL's `query` of a POST that declares `http.query`, each signed token in it
+ * as the claims of its purpose.
+ */
+export type QueryArgs<Q, T = Record<never, never>> = [Q] extends [never] ? unknown
+	: Q extends InputSchema ? { readonly query: WithClaims<z.output<Q>, T> }
+	: unknown
+
+/**
+ * The wire of a procedure: `POST` with a JSON body by default; a query may be `GET`, its input then flat scalar URL
+ * parameters; a POST may read a flat `query` from the URL and take a native form's `urlencoded` body.
+ */
+export interface HttpOption<Q> {
+	readonly method?: 'GET' | 'POST'
+	readonly query?: Q
+	readonly body?: 'json' | 'urlencoded'
+	/**
+	 * A public GET query's successful answers may be reused: `{ maxAgeSeconds }`, or `'immutable'` (a year) when its
+	 * input names an immutable value. Every other answer is `no-store`.
+	 */
+	readonly cache?: EndpointCache
+}
 
 /**
  * What `.handle` answers: the endpoint, or a message the group refuses at the endpoint's line — when the handler
@@ -143,10 +288,24 @@ export interface Endpoint<T extends ProcedureType, I extends InputSchema | null,
 	readonly declared: D
 }
 
-/** An endpoint before `.handle`: a group refuses it. */
-export interface EndpointBuilder<T extends ProcedureType, I extends InputSchema | null, O extends Schema, Acc, D, Ctx> extends PendingEndpoint {
+/**
+ * An endpoint before `.handle`: a group refuses it. `Tk` are the kit's token purposes: a signed token field of the input
+ * reaches the handler as the claims of its purpose.
+ */
+export interface EndpointBuilder<
+	T extends ProcedureType,
+	I extends InputSchema | null,
+	O extends Schema,
+	Acc,
+	D,
+	Ctx,
+	X = unknown,
+	Tk = Record<never, never>,
+> extends PendingEndpoint {
 	/** The endpoint's handler, typed by its access form and declaration; it may return only the output's fields. */
-	handle<const F extends KitHandler<HandlerInput<I, Acc>, Ctx, HandlerReturn<F, O>>>(handler: F): ExactReturn<F, O, Endpoint<T, I, O, Acc, D>>
+	handle<const F extends KitHandler<WithClaims<HandlerInput<I, Acc>, Tk>, Ctx, HandlerReturn<F, O>, X>>(
+		handler: F,
+	): ExactReturn<F, O, Endpoint<T, I, O, Acc, D>>
 }
 
 /** What every endpoint builder has and no handled endpoint has. */
@@ -154,44 +313,71 @@ export interface PendingEndpoint {
 	handle(handler: never): unknown
 }
 
-/** The builders of a group's callback: they know the group's callers, so a handler knows its principal. */
+/**
+ * The builders of a group's callback: they know the group's callers, so a handler knows its principal. A group without
+ * callers (`Caller` is `never`) declares public procedures only.
+ */
 export interface GroupKit<K extends KitTypes, Caller extends RpcCaller> {
 	query<
-		const Acc extends QueryAccess<K['action'], K['dimension'], InputOf<I>>,
+		const Acc extends GroupAccess<Caller, QueryAccess<K['action'], K['dimension'], InputOf<I>>>,
 		O extends Schema,
 		I extends InputSchema | null = null,
 		const S extends 'read' = never,
 		const U extends UnscopedDeclaration<K['tables'], 'read'> = never,
 		const Cn extends readonly ImportOf<K>[] = never,
 		const Is extends string = never,
+		const Acts extends readonly K['action'][] = never,
+		Q extends InputSchema = never,
+		const Sg extends readonly string[] = never,
 	>(
-		def: EndpointDef<I, O, Acc, S, U, Cn, Is, K['index']> & NoKick,
+		def:
+			& EndpointDef<I, O, Acc, S, U, Cn, Is, K['index']>
+			& PublicFields<Acc, Acts>
+			& HttpField<Q, Acc>
+			& NoKick
+			& SignsField<Sg, keyof K['tokens'] & string>
+			& EgressField,
 	): EndpointBuilder<
 		'query',
 		I,
 		O,
 		Acc,
 		Declared<S, U, Cn, Is>,
-		EndpointContext<K, Caller, 'query', CheckedAccess<Acc>, Declared<S, U, Cn, Is>>
+		ProcedureContext<K, Caller, 'query', Acc, Acts, Declared<S, U, Cn, Is>, never, never, Sg>,
+		QueryArgs<Q, K['tokens']>,
+		K['tokens']
 	>
 	mutation<
-		const Acc extends MutationAccess<K['action'], K['dimension'], K['creatable'], InputOf<I>>,
+		const Acc extends GroupAccess<Caller, MutationAccess<K['action'], K['dimension'], K['creatable'], InputOf<I>>>,
 		O extends Schema,
 		I extends InputSchema | null = null,
 		const S extends SqlMode = never,
 		const U extends UnscopedDeclaration<K['tables'], UnscopedMode> = never,
 		const Cn extends readonly ImportOf<K>[] = never,
 		const Is extends string = never,
-		const Th extends string = never,
+		const Acts extends readonly K['action'][] = never,
+		Q extends InputSchema = never,
+		const Ks extends readonly string[] = never,
+		const Bs extends string = never,
+		const Sg extends readonly string[] = never,
 	>(
-		def: EndpointDef<I, O, Acc, S, U, Cn, Is, K['index']> & KickField<Th>,
+		def:
+			& EndpointDef<I, O, Acc, S, U, Cn, Is, K['index']>
+			& PublicFields<Acc, Acts>
+			& HttpField<Q, Acc>
+			& KicksField<Ks>
+			& BindsField<Bs>
+			& SignsField<Sg, keyof K['tokens'] & string>
+			& EgressField,
 	): EndpointBuilder<
 		'mutation',
 		I,
 		O,
 		Acc,
 		Declared<S, U, Cn, Is>,
-		EndpointContext<K, Caller, 'mutation', CheckedAccess<Acc>, Declared<S, U, Cn, Is>>
+		ProcedureContext<K, Caller, 'mutation', Acc, Acts, Declared<S, U, Cn, Is>, Ks, Bs, Sg>,
+		QueryArgs<Q, K['tokens']>,
+		K['tokens']
 	>
 }
 
@@ -229,8 +415,8 @@ export type PendingIn<T, Path extends string> = typeof failedBuild extends keyof
 	: string extends keyof T ? [IsPending<T[string & keyof T]>] extends [true] ? `${Path}* (its type admits an endpoint without a handler)` : never
 	: { [K in keyof T]: [IsPending<T[K]>] extends [true] ? `${Path}${K & string}` : never }[keyof T]
 
-/** `app.group(…)`: endpoints for one set of callers, declared in any module and mounted by the contract. */
-export interface Group<C extends readonly [RpcCaller, ...RpcCaller[]], T extends GroupInput> {
+/** `app.group(…)`: endpoints for one set of callers (none for a group of public procedures), mounted by the contract. */
+export interface Group<C extends readonly RpcCaller[], T extends GroupInput> {
 	readonly '~kind': 'group'
 	readonly callers: C
 	readonly endpoints: T
@@ -246,21 +432,42 @@ export interface LinkGroupKit<K extends KitTypes, LD extends string, G extends s
 		const U extends UnscopedDeclaration<K['tables'], 'read'> = never,
 	>(
 		def: EndpointDef<I, O, Acc, S, U, never, never, K['index']> & NoKick,
-	): EndpointBuilder<'query', I, O, Acc, Declared<S, U, never, never>, LinkContext<K, 'query', LD, Acc['action'], Declared<S, U, never, never>>>
+	): EndpointBuilder<
+		'query',
+		I,
+		O,
+		Acc,
+		Declared<S, U, never, never>,
+		LinkContext<K, 'query', LD, Acc['action'], Declared<S, U, never, never>>,
+		unknown,
+		K['tokens']
+	>
 	mutation<
 		const Acc extends LinkAccess<G>,
 		O extends Schema,
 		I extends InputSchema | null = null,
 		const S extends SqlMode = never,
 		const U extends UnscopedDeclaration<K['tables'], UnscopedMode> = never,
-		const Th extends string = never,
+		const Ks extends readonly string[] = never,
 	>(
-		def: EndpointDef<I, O, Acc, S, U, never, never, K['index']> & KickField<Th>,
-	): EndpointBuilder<'mutation', I, O, Acc, Declared<S, U, never, never>, LinkContext<K, 'mutation', LD, Acc['action'], Declared<S, U, never, never>>>
+		def: EndpointDef<I, O, Acc, S, U, never, never, K['index']> & KicksField<Ks>,
+	): EndpointBuilder<
+		'mutation',
+		I,
+		O,
+		Acc,
+		Declared<S, U, never, never>,
+		LinkContext<K, 'mutation', LD, Acc['action'], Declared<S, U, never, never>> & KickContext<Ks>,
+		unknown,
+		K['tokens']
+	>
 }
 
 /** An export procedure names its action and its scope; `{ member: true }` would give the consumer's key nothing to hold. */
-export type ExportAccess<A extends string, D extends string, In> = Exclude<QueryAccess<A, D, In>, MemberAccess | AppAccess<A>>
+export type ExportAccess<A extends string, D extends string, In> = Exclude<
+	QueryAccess<A, D, In>,
+	MemberAccess | AppAccess<A> | CapabilitiesAccess<{ readonly [name: string]: CapabilityAccess<A, D, In> }>
+>
 
 /** The builder of an export's callback: queries only, run read-only. */
 export interface ExportKit<K extends KitTypes> {

package/src/contract/index.ts

@@ -19,6 +19,7 @@ export {
 	exportDescription,
 	exportDescriptionSchema,
 	incompatibleChanges,
+	incompatibleMountChanges,
 	parseExportDescription,
 	type SnapshotProcedure,
 } from './connect'
@@ -26,9 +27,26 @@ export type * from './context'
 export * from './declaration'
 export * from './defaults'
 export * from './define'
+export { type ClientInput, file, type FileBrand, type FileMark, fileOf, type FileRef, type FileSchema, type FileStatus } from './file'
 export type * from './group'
 export * from './kit'
 export { schemaFromContract } from './platform'
 export { ContractError } from './problems'
+export { type Redirect, redirect, type RedirectBrand, type RedirectMark, redirectOf, type RedirectOptions } from './redirect'
 export { SNAPSHOT_DIRECTORY, type SnapshotNames, snapshotNames, snapshotSource } from './snapshot-source'
+export {
+	SIGNED_TOKEN_MAX_LENGTH,
+	signedToken,
+	type SignedTokenMark,
+	signedTokenOf,
+	type SignedTokenSchema,
+	token,
+	TOKEN_MAX_DAYS,
+	type TokenOptions,
+	type TokenPurpose,
+	type TokenPurposes,
+	type TokenSigning,
+	type WithClaims,
+} from './token'
 export * from './vocabulary'
+export { type WebhookBindings, WebhookSecret } from './webhook-binding'