wirejs-resources 0.1.191 → 0.1.192

package/README.md

@@ -1,3 +1,114 @@
-Experimental.
+# wirejs-resources
 
-If this package interests you, contact the author.
+> **Experimental:** WireJS is an experimental hobby project and is not production software. For a professionally supported project in a similar spirit, see [AWS Blocks](https://github.com/aws-devtools-labs/aws-blocks), which benefits from lessons and ideas explored here.
+
+Experimental deployment-neutral resources, request context, and service abstractions for WireJS applications.
+
+This package can be used by WireJS apps, API modules, SSR/SSG code, deployment adapters, or other Node code that wants cloud/host/provider-agnostic resource abstractions. App code describes what it needs; local and deployment-specific packages decide how those resources are implemented.
+
+## What is in this package?
+
+- `Resource` — the base identity/scope model used by all resources.
+- `Context`, `CookieJar`, `SignedCookie` — request/runtime context and cookie helpers.
+- Data/config resources — `Setting`, `KeyValueStore`, `DistributedTable`.
+- Invocation resources — `Endpoint`, `BackgroundJob`, `CronJob`.
+- Runtime metadata — `SystemAttribute`.
+- Services — `FileService`, `AuthenticationService`, OIDC provider presets, `RealtimeService`, `LLM`, `EmailSender`.
+- Override hooks — deployment packages can swap local implementations for cloud/provider implementations.
+
+## Detailed docs
+
+- [Core concepts: resources, scopes, overrides, and context](./docs/core.md)
+- [Data/config resources: Setting, KeyValueStore, DistributedTable](./docs/data-resources.md)
+- [Invocation resources: Endpoint, BackgroundJob, CronJob, SystemAttribute](./docs/invocation-resources.md)
+- [Services: FileService, AuthenticationService, RealtimeService, LLM, EmailSender](./docs/services.md)
+
+## Quick example
+
+```ts
+import {
+	Context,
+	DistributedTable,
+	Endpoint,
+	PassThruParser,
+	Setting,
+} from 'wirejs-resources';
+
+const siteTitle = new Setting('site', 'title', {
+	private: false,
+	description: 'Human-readable site title',
+	init: () => 'My WireJS app',
+});
+
+type Todo = {
+	userId: string;
+	id: string;
+	status: 'open' | 'done';
+	title: string;
+};
+
+const todos = new DistributedTable('app', 'todos', {
+	parse: PassThruParser<Todo>,
+	key: {
+		partition: { field: 'userId', type: 'string' },
+		sort: { field: 'id', type: 'string' },
+	},
+	indexes: [
+		{ partition: { field: 'status', type: 'string' } },
+	],
+});
+
+new Endpoint('api', 'open-todos', {
+	path: '/open-todos',
+	description: 'List open todos for a user.',
+	handle: async (context: Context) => {
+		const userId = context.location.searchParams.get('userId') ?? 'anonymous';
+		const title = await siteTitle.read();
+		const items = [];
+
+		for await (const todo of todos.query({
+			by: 'userId-id',
+			where: { userId },
+			filter: { status: { eq: 'open' } },
+		})) {
+			items.push(todo);
+		}
+
+		context.responseHeaders['content-type'] = 'application/json; charset=utf-8';
+		return JSON.stringify({ title, items });
+	},
+});
+```
+
+## Exports
+
+Common exports include:
+
+```ts
+import {
+	Context,
+	CookieJar,
+	SignedCookie,
+	Resource,
+	Setting,
+	DistributedTable,
+	PassThruParser,
+	KeyValueStore,
+	Endpoint,
+	BackgroundJob,
+	CronJob,
+	SystemAttribute,
+	FileService,
+	AuthenticationService,
+	GoogleOIDCProvider,
+	GitHubOIDCProvider,
+	RealtimeService,
+	LLM,
+	EmailSender,
+	overrides,
+	withContext,
+	requiresContext,
+} from 'wirejs-resources';
+```
+
+WireJS is experimental. Expect breaking changes and check the README/docs installed with your exact package version after upgrading.

package/docs/core.md

@@ -0,0 +1,147 @@
+# Core concepts
+
+## Resource identity and scope
+
+`Resource` is the base class for resources and services. A resource is identified by a `scope` and an `id`; together they produce an `absoluteId`.
+
+```ts
+import { Resource } from 'wirejs-resources';
+
+const app = new Resource('apps', 'store');
+const child = new Resource(app, 'uploads');
+
+console.log(app.absoluteId);   // apps/store
+console.log(child.absoluteId); // apps/store/uploads
+```
+
+Use stable IDs. Deployment adapters use `absoluteId` values to provision or locate provider resources. Changing IDs in a deployed app can create new infrastructure or orphan old data.
+
+## Local defaults and deployment overrides
+
+The default implementations are intentionally local-development friendly. For example, local `FileService` writes under `temp/wirejs-services`, and local `EmailSender` writes messages to `.outbox`.
+
+Deployment packages can replace implementations through `overrides`, allowing app code to keep constructing the same resources while storage, auth, email, realtime, etc. move to cloud/provider-backed implementations.
+
+```ts
+import { overrides, FileService } from 'wirejs-resources';
+
+// Deployment packages normally do this, not app code.
+overrides.FileService = class ProviderFileService extends FileService {
+	// provider-backed implementation
+};
+```
+
+## Context
+
+`Context` represents a request/runtime invocation. It is used by SSR handlers, endpoints, API methods that need request state, and service code that has to inspect or mutate response details.
+
+Important properties:
+
+- `location: URL` — current request URL. Assigning a new URL/string marks `locationIsDirty`.
+- `locationIsDirty: boolean` — response layers can use this to emit redirects.
+- `cookies: CookieJar` — mutable request/response cookie jar.
+- `httpMethod?: string`
+- `requestHeaders: Record<string, string | string[]>`
+- `requestBody?: string`
+- `responseHeaders: Record<string, string>`
+- `responseCode?: number`
+- `systemInfo` — iterable of static and runtime `SystemAttribute`s.
+
+```ts
+import type { Context } from 'wirejs-resources';
+
+export async function redirectToLogin(context: Context) {
+	context.location = new URL('/login', context.location.origin);
+	context.responseCode = 302;
+	context.responseHeaders['cache-control'] = 'no-store';
+	return '';
+}
+```
+
+## Cookies
+
+`CookieJar` parses request cookies and tracks response cookie changes. Use it when endpoint/API/SSR code needs request cookies or needs to set values for the response pipeline.
+
+```ts
+const value = context.cookies.get('theme')?.value;
+
+context.cookies.set({
+	name: 'theme',
+	value: 'dark',
+	path: '/',
+	maxAge: 60 * 60 * 24 * 365,
+	secure: true,
+	httpOnly: false,
+});
+
+context.cookies.delete('old-cookie');
+```
+
+`getAll()` returns plain request/current cookie values. `getSetCookies()` returns only cookies that were changed and need `Set-Cookie` response headers.
+
+## SignedCookie
+
+`SignedCookie<T>` is a public low-level helper for tamper-evident cookie state. It stores the value as a signed JWT in a cookie. Consumers can use it directly when they want small authenticated cookie payloads, but it is not encrypted: do not put secrets in the payload unless you are comfortable with clients being able to read them. For auth specifically, prefer `AuthenticationService` unless you are building a custom auth/session layer.
+
+```ts
+import { Setting, SignedCookie } from 'wirejs-resources';
+
+type Flash = { message: string; level: 'info' | 'error' };
+
+const signingSecret = new Setting('ui', 'flash-cookie-secret', {
+	private: true,
+	init: 'random',
+	description: 'Signs flash message cookies.',
+});
+
+const flashCookie = new SignedCookie<Flash>(
+	'ui',
+	'flash',
+	signingSecret,
+	{
+		maxAge: 60,
+		httpOnly: true,
+		secure: true,
+		path: '/',
+	}
+);
+
+await flashCookie.write(context.cookies, {
+	message: 'Saved successfully.',
+	level: 'info',
+});
+
+const flash = await flashCookie.read(context.cookies);
+await flashCookie.write(context.cookies, null); // clears the cookie
+```
+
+Behavior:
+
+- Cookie names are prefixed by scope, e.g. `ui-flash` or `app-auth-identity`.
+- `read()` returns `T | null`; invalid signatures and expired tokens return `null`.
+- `write(cookies, value)` signs and sets the cookie.
+- `write(cookies, null)` or `clear(cookies)` deletes it.
+- Default signed-cookie options are `httpOnly: true`, `secure: true`, and one-hour max age unless overridden.
+
+## Context-wrapped APIs
+
+`withContext()` and `requiresContext()` are helpers for APIs where some methods need the active request context but callers should still see a convenient method namespace.
+
+```ts
+import { Context, withContext } from 'wirejs-resources';
+
+export const userApi = withContext((context: Context) => ({
+	profile: {
+		async current() {
+			return { path: context.location.pathname };
+		},
+	},
+}));
+
+// Later, with an active context:
+const profile = await userApi.profile.current(context);
+```
+
+## System information
+
+`SystemAttribute` values expose deployment/runtime facts such as deployment type, local/public origins, or provider capabilities. Static attributes are registered by code; runtime attributes are supplied by hosting/deployment layers and exposed through `context.systemInfo`.

package/docs/data-resources.md

@@ -0,0 +1,182 @@
+# Data and configuration resources
+
+## Setting
+
+`Setting` represents a typed configuration value. Settings are stored in an internal `KeyValueStore` and are registered at construction time so admin/config tools can discover them.
+
+```ts
+import { Setting } from 'wirejs-resources';
+
+export const theme = new Setting('site', 'theme', {
+	private: false,
+	description: 'Public site theme',
+	options: ['light', 'dark'] as const,
+	init: () => 'light',
+});
+
+const current = await theme.read(); // 'light' | 'dark' | undefined
+await theme.write('dark');
+```
+
+Options:
+
+- `private` — marks secrets or internal settings. UIs should avoid displaying values for private settings.
+- `description` — human-readable explanation.
+- `options` — valid string options; also improves TypeScript inference.
+- `init` — optional lazy initializer. Use a function for defaults or `'random'` for generated secret material.
+
+```ts
+const jwtSecret = new Setting('auth', 'jwt-secret', {
+	private: true,
+	description: 'Signs auth/session tokens.',
+	init: 'random',
+});
+```
+
+`read()` initializes the setting only when no value exists. `write(value, { onlyIfNotExists: true })` is useful when multiple processes may race to initialize the same value.
+
+Discovery:
+
+```ts
+for (const setting of Setting.list()) {
+	console.log(setting.absoluteId, setting.description, setting.isPrivate);
+}
+```
+
+## KeyValueStore
+
+`KeyValueStore<T>` is a simple string-keyed data store.
+
+```ts
+import { KeyValueStore } from 'wirejs-resources';
+
+type Session = { userId: string; expiresAt: string };
+const sessions = new KeyValueStore<Session>('auth', 'sessions');
+
+await sessions.set('session-id', {
+	userId: 'user-1',
+	expiresAt: new Date(Date.now() + 3600_000).toISOString(),
+});
+
+const session = await sessions.get('session-id');
+await sessions.delete('session-id');
+```
+
+Scanning:
+
+```ts
+for await (const { key, value } of sessions.scan()) {
+	console.log(key, value.userId);
+}
+```
+
+Use `KeyValueStore` for simple lookup data. Use `DistributedTable` when records need typed keys, range/query patterns, indexes, or filtering.
+
+## DistributedTable
+
+`DistributedTable` is a deployment-neutral table abstraction for structured records. It favors provider mappings that scale across partitions, similar to DynamoDB-style table design.
+
+```ts
+import { DistributedTable, PassThruParser } from 'wirejs-resources';
+
+type Todo = {
+	userId: string;
+	id: string;
+	status: 'open' | 'done';
+	createdAt: string;
+	title: string;
+};
+
+export const todos = new DistributedTable('app', 'todos', {
+	parse: PassThruParser<Todo>,
+	key: {
+		partition: { field: 'userId', type: 'string' },
+		sort: { field: 'id', type: 'string' },
+	},
+	indexes: [
+		{
+			partition: { field: 'status', type: 'string' },
+			sort: { field: 'createdAt', type: 'string' },
+		},
+	],
+});
+```
+
+### Parser
+
+`parse` runs when records are read. Use `PassThruParser<T>` for trusted internal data, or provide a validation/parser function when data needs runtime checking.
+
+```ts
+function parseTodo(record: Record<string, any>): Todo {
+	if (typeof record.userId !== 'string') throw new Error('Invalid userId');
+	if (typeof record.id !== 'string') throw new Error('Invalid id');
+	if (record.status !== 'open' && record.status !== 'done') throw new Error('Invalid status');
+	return record as Todo;
+}
+```
+
+### Save, get, delete
+
+```ts
+await todos.save({
+	userId: 'u1',
+	id: 't1',
+	status: 'open',
+	createdAt: new Date().toISOString(),
+	title: 'Write docs',
+}, { onlyIfNotExists: true });
+
+const todo = await todos.get({ userId: 'u1', id: 't1' });
+await todos.delete({ userId: 'u1', id: 't1' });
+```
+
+### Query
+
+`query()` targets a primary key or named index. Index names are derived from fields: partition-only `status`; partition+sort `status-createdAt`; primary key `userId-id`.
+
+```ts
+for await (const todo of todos.query({
+	by: 'userId-id',
+	where: { userId: 'u1' },
+	filter: { status: { eq: 'open' } },
+})) {
+	console.log(todo.title);
+}
+```
+
+```ts
+for await (const todo of todos.query({
+	by: 'status-createdAt',
+	where: {
+		status: 'open',
+		createdAt: { beginsWith: '2026-07' },
+	},
+})) {
+	console.log(todo.title);
+}
+```
+
+### Filters
+
+Filters support field comparisons and composition:
+
+```ts
+const filter = {
+	and: [
+		{ status: { eq: 'open' } },
+		{ createdAt: { between: ['2026-07-01', '2026-08-01'] } },
+		{ not: { title: { beginsWith: '[archived]' } } },
+	],
+};
+```
+
+Supported operators: `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `between`, `beginsWith`, `and`, `or`, `not`.
+
+### Design guidance
+
+- Choose partition keys carefully. Changing key definitions in production can be destructive for some providers.
+- Prefer high-cardinality, non-sequential partition keys for scalable distribution.
+- Use sort keys for ordered/range access within a partition.
+- Use indexes for alternate access patterns.
+- Avoid `scan()` for large production tables unless you expect the cost.
+- Local development may implement queries as scans; production overrides should map to provider-native queries/indexes where possible.

package/docs/invocation-resources.md

@@ -0,0 +1,179 @@
+# Invocation and runtime resources
+
+## Endpoint
+
+Most app/API code should not define or call raw HTTP routes. WireJS APIs are normally imported like modules from client, SSR, and SSG code; the framework handles the server call protocol invisibly while preserving TypeScript types.
+
+Use `Endpoint` only when you intentionally need a real HTTP path outside that WireJS module protocol. Common reasons include:
+
+- webhooks and third-party callbacks;
+- OIDC/provider callback paths;
+- custom admin/settings portals;
+- compatibility routes for callers that cannot import the WireJS API package;
+- serving non-API content from an API module, such as generated images, files, feeds, or health-check text.
+
+`Endpoint` registers an HTTP-accessible handler outside the normal generated API method surface.
+
+```ts
+import { Endpoint } from 'wirejs-resources';
+
+new Endpoint('webhooks', 'stripe', {
+	path: '/webhooks/stripe',
+	description: 'Stripe webhook receiver',
+	handle: async context => {
+		const signature = context.requestHeaders['stripe-signature'];
+		const body = context.requestBody;
+
+		context.responseHeaders['content-type'] = 'text/plain; charset=utf-8';
+		return 'ok';
+	},
+});
+```
+
+Options:
+
+- `path` — optional route. If omitted, the endpoint path is derived from `absoluteId`.
+- `handle(context)` — request handler. Current endpoint handlers return strings/promises of strings.
+- `description` — human-readable purpose.
+
+Wildcard-style paths may end in `%` for hosting layers that support pattern matching.
+
+```ts
+new Endpoint('files', 'public-prefix', {
+	path: '/public/%',
+	handle: async context => `Requested ${context.location.pathname}`,
+});
+```
+
+Example generated image endpoint:
+
+```ts
+new Endpoint('images', 'og-card', {
+	path: '/og-card.svg',
+	description: 'Generate an OpenGraph image.',
+	handle: async context => {
+		const title = context.location.searchParams.get('title') ?? 'Untitled';
+		context.responseHeaders['content-type'] = 'image/svg+xml; charset=utf-8';
+		return `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630">
+			<rect width="1200" height="630" fill="#111" />
+			<text x="80" y="320" fill="white" font-size="72">${title}</text>
+		</svg>`;
+	},
+});
+```
+
+`Endpoint.list()` and `Endpoint.get(key)` expose registered endpoints for hosting/deployment discovery.
+
+`determineUrl()` combines the endpoint path with the `wirejs/endpoint-origin` setting. This is useful when registering webhook URLs with external services.
+
+```ts
+const url = await endpoint.determineUrl();
+```
+
+## BackgroundJob
+
+`BackgroundJob` schedules work that should continue after the current request/action has scheduled it.
+
+```ts
+import { BackgroundJob } from 'wirejs-resources';
+
+export const sendReceipt = new BackgroundJob('orders', 'send-receipt', {
+	handler: async (orderId: string) => {
+		// Recreate clients/resources inside the handler as needed.
+		// Send email, call external APIs, update tables, etc.
+	},
+});
+
+await sendReceipt.start('order-123');
+```
+
+Important behavior:
+
+- `start()` resolves when the job is scheduled, not when the handler completes.
+- Arguments are JSON-serialized/deserialized before local execution to mimic cloud behavior.
+- Handlers may run in a different process/environment from the caller.
+- Do not depend on request-local state, closures, globals, or in-memory caches unless the handler recreates them safely.
+- Local development currently does not enforce timeouts.
+
+Good pattern:
+
+```ts
+const resizeAvatar = new BackgroundJob('users', 'resize-avatar', {
+	handler: async (userId: string, avatarFile: string) => {
+		const files = createUserFileService(userId);
+		const original = await files.read(avatarFile);
+		// resize and write output
+	},
+});
+```
+
+Avoid:
+
+```ts
+let currentRequestUser: string | undefined;
+
+const job = new BackgroundJob('bad', 'closure-state', {
+	// This may not be the same process or value when the job runs.
+	handler: async () => console.log(currentRequestUser),
+});
+```
+
+## CronJob
+
+`CronJob` registers recurring work using a cron expression.
+
+```ts
+import { CronJob } from 'wirejs-resources';
+
+new CronJob('maintenance', 'nightly-cleanup', {
+	schedule: '0 3 * * *',
+	handler: async () => {
+		// delete expired sessions, compact data, sync reports, etc.
+	},
+});
+```
+
+Create cron jobs at module top level. Deployment adapters discover registered jobs and map them to provider schedulers. Dynamically creating cron jobs inside request handlers is not supported as a deployment model.
+
+A `CronJob` can invoke a `BackgroundJob` if you want the same work to be triggerable manually and on a schedule:
+
+```ts
+const syncReports = new BackgroundJob('reports', 'sync', {
+	handler: async () => {
+		// sync reports
+	},
+});
+
+new CronJob('reports', 'hourly-sync', {
+	schedule: '0 * * * *',
+	handler: async () => syncReports.start(),
+});
+```
+
+## SystemAttribute
+
+`SystemAttribute` describes runtime/deployment metadata. Hosting layers can attach runtime attributes to `Context`; app code can also define static attributes.
+
+Use cases:
+
+- expose deployment type;
+- expose local/network/public origins;
+- expose provider capabilities;
+- provide diagnostics in admin screens.
+
+```ts
+import { SystemAttribute } from 'wirejs-resources';
+
+new SystemAttribute('app', 'support-email', {
+	description: 'Support contact displayed in diagnostics.',
+	value: 'support@example.com',
+});
+```
+
+Reading from context:
+
+```ts
+for (const attr of context.systemInfo) {
+	console.log(attr.absoluteId, attr.value);
+}
+```

package/docs/services.md

@@ -0,0 +1,361 @@
+# Services
+
+Services are resource-scoped abstractions for capabilities that may have different local and production implementations.
+
+## FileService
+
+`FileService` is resource-scoped file/blob-like storage.
+
+```ts
+import { FileService, Resource } from 'wirejs-resources';
+
+const uploadsScope = new Resource('app', 'uploads');
+const files = new FileService(uploadsScope, 'images');
+
+await files.write('avatar.txt', 'hello');
+const text = await files.read('avatar.txt');
+
+for await (const filename of files.list()) {
+	console.log(filename);
+}
+
+await files.delete('avatar.txt');
+```
+
+Default local behavior writes under:
+
+```text
+temp/wirejs-services/<resource-id>/...
+```
+
+Use `onlyIfNotExists` to avoid overwriting existing files:
+
+```ts
+await files.write('lock.json', '{}', { onlyIfNotExists: true });
+```
+
+Deployment overrides can map `FileService` to object stores, buckets, or provider file/blob services.
+
+## AuthenticationService
+
+`AuthenticationService` is the authentication abstraction used by app/API code to inspect and manage auth state. The local implementation provides username/password signup/signin/change-password/signout backed by `FileService` plus signed-cookie session state. It can also be configured with OIDC providers.
+
+Construct it at module scope, then expose its context-wrapped API from your API module:
+
+```ts
+import { AuthenticationService } from 'wirejs-resources';
+
+export const authService = new AuthenticationService('app', 'auth', {
+	keepalive: true,
+	cookie: 'identity',
+});
+
+export const auth = authService.buildApi();
+```
+
+The API returned by `buildApi()` includes:
+
+- `getState(context)` — returns an `AuthenticationMachineState` for UI state machines.
+- `setState(context, input)` — performs actions such as `signin`, `signup`, `signout`, `changepassword`, or OIDC actions.
+- `getCurrentUser(context)` — returns the current user or `null`.
+- `requireCurrentUser(context)` — returns the current user or throws `Unauthorized.`.
+
+Example endpoint-style use:
+
+```ts
+const user = await auth.requireCurrentUser(context);
+return `Hello ${user.displayName}`;
+```
+
+Machine-state example:
+
+```ts
+const state = await auth.getState(context);
+
+if (state.state === 'unauthenticated') {
+	console.log(Object.keys(state.actions)); // signin, signup, OIDC actions, ...
+}
+
+const result = await auth.setState(context, {
+	key: 'signin',
+	inputs: {
+		username: 'alice',
+		password: 'correct horse battery staple',
+	},
+});
+```
+
+Constructor options include:
+
+- `keepalive` — refreshes authenticated cookie state while active.
+- `cookie` — cookie-name suffix; the final cookie name is scope-prefixed.
+- `oidcProviders` — provider definitions for OIDC signin flows.
+
+OIDC provider presets are exported for common providers:
+
+```ts
+import {
+	AuthenticationService,
+	GoogleOIDCProvider,
+	GitHubOIDCProvider,
+} from 'wirejs-resources';
+
+export const authService = new AuthenticationService('app', 'auth', {
+	oidcProviders: [
+		GoogleOIDCProvider,
+		GitHubOIDCProvider,
+	],
+});
+```
+
+Available presets include Google, Facebook, GitHub, and Apple. Provider flows generally also require client IDs/secrets or deployment-specific configuration; check the active deployment package and installed TypeScript types for the exact wiring.
+
+Deployment providers may back this with hosted identity, OIDC flows, signed cookies, or other mechanisms.
+
+## RealtimeService
+
+`RealtimeService<T>` provides channel-based server-to-client message streams. The local implementation uses WebSockets and signed channel tokens.
+
+```ts
+import { RealtimeService } from 'wirejs-resources';
+
+type TodoEvent =
+	| { type: 'created'; id: string; title: string }
+	| { type: 'completed'; id: string };
+
+const realtime = new RealtimeService<TodoEvent>('app', 'todo-events');
+```
+
+Publishing from server/API code:
+
+```ts
+await realtime.publish('user-u1', [
+	{ type: 'created', id: 't1', title: 'Write docs' },
+]);
+```
+
+Creating a stream descriptor for the client:
+
+```ts
+const stream = await realtime.getStream(context, 'user-u1');
+```
+
+The returned value is typed as `MessageStream<T>`, but in practice it carries metadata that the WireJS client/runtime can use to subscribe to the websocket channel. Channel names are intentionally restricted for provider portability: up to five slash-separated segments; each segment is 1-50 alphanumeric/dash characters.
+
+Use cases:
+
+- server-to-client notifications;
+- table/resource update broadcasts;
+- collaborative UI updates;
+- low-volume realtime app events.
+
+Deployment overrides can map realtime channels to provider websocket/pubsub infrastructure.
+
+## LLM
+
+`LLM` represents a large-language-model endpoint/configuration with model preferences, optional system prompt, target context size, and tool schemas.
+
+Conversation messages use OpenAI-like roles:
+
+- `user`
+- `assistant`
+- `tool`
+
+### One-shot responses
+
+For a clean one-shot response, omit `onChunk` and await the returned assistant message:
+
+```ts
+import { LLM } from 'wirejs-resources';
+
+const assistant = new LLM('ai', 'assistant', {
+	models: ['llama3.1', 'gpt-4o-mini'],
+	systemPrompt: 'You answer concisely.',
+});
+
+const reply = await assistant.continueConversation({
+	history: [
+		{ role: 'user', content: 'Summarize our refund policy in one paragraph.' },
+	],
+});
+
+console.log(reply.content);
+```
+
+### Streaming responses
+
+Use `onChunk` when you want to update UI progressively, persist partial output, or broadcast partial responses over realtime channels:
+
+```ts
+const reply = await assistant.continueConversation({
+	history: [
+		{ role: 'user', content: 'Where is my order?' },
+	],
+	onChunk: chunk => {
+		if (chunk.message.role === 'assistant') {
+			console.log(chunk.message.content);
+		}
+	},
+});
+
+console.log('final:', reply.content);
+```
+
+### Background orchestration
+
+`LLM` does not schedule background work by itself. `continueConversation()` runs in the current server execution. For chat-style UX, long tool loops, or request-independent processing, start the workflow from an app-owned `BackgroundJob` or equivalent API orchestration and store/broadcast progress yourself.
+
+```ts
+import { BackgroundJob, LLM, RealtimeService } from 'wirejs-resources';
+
+const assistant = new LLM('ai', 'assistant', {
+	models: ['llama3.1'],
+});
+
+const updates = new RealtimeService<{ room: string; text: string }>('ai', 'updates');
+
+export const respondInBackground = new BackgroundJob('ai', 'respond', {
+	handler: async (room: string, prompt: string) => {
+		const reply = await assistant.continueConversation({
+			history: [{ role: 'user', content: prompt }],
+			onChunk: async chunk => {
+				if (chunk.message.role === 'assistant') {
+					await updates.publish(room, [{ room, text: chunk.message.content }]);
+				}
+			},
+		});
+
+		// Persist final reply in app storage here if needed.
+		await updates.publish(room, [{ room, text: reply.content }]);
+	},
+});
+
+// API/endpoint code can schedule and return quickly:
+await respondInBackground.start('room-1', 'Write a short welcome message.');
+```
+
+### Tool calling
+
+`LLM` provides model-side tool-calling support, not tool execution. The `ToolDefinition` exported by `wirejs-resources` describes tools to the model. Application code owns the tool execution loop: call the model, inspect `assistant.tool_calls`, execute matching server-side functions, append a `tool` message with results, then call the model again.
+
+The generated app template contains a fuller chat/tool example under `api/apps/llm/`:
+
+- `tools.ts` defines tool schemas plus `execute()` functions.
+- `tooled-handler.ts` loops over `tool_calls`, runs matching tools, and appends `ToolMessage` results.
+- `infra.ts` handles conversation persistence, streaming chunks, realtime status messages, and calls to `LLM.continueConversation()`.
+
+Minimal tool-loop shape:
+
+```ts
+import {
+	LLM,
+	ToolDefinition as BaseToolDefinition,
+	type LLMMessage,
+	type ToolMessage,
+} from 'wirejs-resources';
+
+type ExecutableTool = BaseToolDefinition & {
+	execute(args: Record<string, any>): Promise<unknown>;
+};
+
+const tools: ExecutableTool[] = [
+	{
+		name: 'lookup_order',
+		description: 'Look up an order by ID.',
+		parameters: {
+			type: 'object',
+			properties: {
+				orderId: { type: 'string', description: 'Order ID' },
+			},
+			required: ['orderId'],
+		},
+		async execute({ orderId }) {
+			// This runs on the server. Validate args and enforce authz here.
+			return { orderId, status: 'shipped' };
+		},
+	},
+];
+
+const assistant = new LLM('ai', 'support-assistant', {
+	models: ['llama3.1', 'gpt-4o-mini'],
+	systemPrompt: 'You help users with account questions.',
+	targetContextSize: 16_384,
+});
+
+const history: LLMMessage[] = [
+	{ role: 'user', content: 'Where is order 123?' },
+];
+
+for (let remainingToolRounds = 5; remainingToolRounds > 0; remainingToolRounds--) {
+	const response = await assistant.continueConversation({
+		history,
+		tools,
+	});
+	history.push(response);
+
+	if (!response.tool_calls?.length) break;
+
+	const toolMessage: ToolMessage = { role: 'tool', content: [] };
+	for (const call of response.tool_calls) {
+		const tool = tools.find(t => t.name === call.function.name);
+		try {
+			if (!tool) throw new Error(`Unknown tool: ${call.function.name}`);
+			const result = await tool.execute(call.function.arguments);
+			toolMessage.content.push({
+				id: call.id || JSON.stringify([call.function.name, call.function.arguments]),
+				content: JSON.stringify(result, null, 2),
+			});
+		} catch (error) {
+			toolMessage.content.push({
+				id: call.id || JSON.stringify([call.function.name, call.function.arguments]),
+				content: String(error),
+				isError: true,
+			});
+		}
+	}
+
+	history.push(toolMessage);
+}
+```
+
+Provider availability and exact model behavior depend on the active implementation.
+
+## EmailSender
+
+`EmailSender` sends email through either a specific sender address or a sender domain. The local implementation writes JSON files to `.outbox/`.
+
+Specific address:
+
+```ts
+import { EmailSender } from 'wirejs-resources';
+
+const mailer = new EmailSender('notifications', 'main', {
+	from: 'hello@example.com',
+});
+
+await mailer.send({
+	to: 'user@example.com',
+	subject: 'Welcome',
+	body: 'Thanks for trying WireJS.',
+	html: '<p>Thanks for trying WireJS.</p>',
+});
+```
+
+Domain sender:
+
+```ts
+const domainMailer = new EmailSender('notifications', 'domain', {
+	fromDomain: 'example.com',
+});
+
+await domainMailer.send({
+	from: 'receipts@example.com',
+	to: ['buyer@example.net'],
+	subject: 'Receipt',
+	body: 'Your receipt is attached.',
+});
+```
+
+When using `fromDomain`, each message must provide `from`, and it must end with the configured domain. This lets deployments verify one domain while still allowing multiple sender addresses within that domain.
+
+Local `.outbox` files are useful for development and tests; production overrides should map to provider email services.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "wirejs-resources",
-	"version": "0.1.191",
+	"version": "0.1.192",
 	"description": "Basic services and server-side resources for wirejs apps",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -44,6 +44,7 @@
 	"files": [
 		"package.json",
 		"README.md",
+		"docs/*",
 		"dist/*"
 	]
 }