@pikku/core 0.12.143 → 0.12.145

package/dist/services/content-service.d.ts

@@ -1,4 +1,12 @@
+/**
+ * Whether stored content is served only through signed URLs (`private`) or at a
+ * plain URL anyone can fetch (`public`).
+ */
 export type ContentVisibility = 'private' | 'public';
+/**
+ * Arguments for signing a URL to one stored object, valid inside the given time
+ * window.
+ */
 export interface SignContentKeyArgs<TBucket extends string = string> {
     bucket: TBucket;
     contentKey: string;
@@ -6,11 +14,18 @@ export interface SignContentKeyArgs<TBucket extends string = string> {
     dateLessThan: Date;
     dateGreaterThan?: Date;
 }
+/**
+ * Arguments for signing an arbitrary URL, valid inside the given time window.
+ */
 export interface SignURLArgs {
     url: string;
     dateLessThan: Date;
     dateGreaterThan?: Date;
 }
+/**
+ * Arguments for a pre-signed upload. `size` and `contentType` are checked
+ * against the bucket's policy by the implementation.
+ */
 export interface GetUploadURLArgs<TBucket extends string = string> {
     bucket: TBucket;
     fileKey: string;
@@ -18,26 +33,45 @@ export interface GetUploadURLArgs<TBucket extends string = string> {
     size?: number;
     visibility?: ContentVisibility;
 }
+/**
+ * Where and how the client should upload, and the key the file will be stored
+ * under.
+ */
 export interface UploadURLResult {
     uploadUrl: string;
     assetKey: string;
     uploadHeaders?: Record<string, string>;
     uploadMethod?: 'PUT' | 'POST';
 }
+/** Identifies one stored object. */
 export interface BucketKeyArgs<TBucket extends string = string> {
     bucket: TBucket;
     key: string;
     visibility?: ContentVisibility;
 }
+/**
+ * Identifies an object to download and how long a signed URL for it should stay
+ * valid.
+ */
 export interface GetDownloadURLArgs<TBucket extends string = string> extends BucketKeyArgs<TBucket> {
     expiresInSeconds?: number;
 }
+/** An object to write from a stream. */
 export interface WriteFileArgs<TBucket extends string = string> extends BucketKeyArgs<TBucket> {
     stream: ReadableStream | NodeJS.ReadableStream;
 }
+/** An object to write from a file already on local disk. */
 export interface CopyFileArgs<TBucket extends string = string> extends BucketKeyArgs<TBucket> {
     fromAbsolutePath: string;
 }
+/**
+ * File storage behind the `content` service: uploads, downloads and signed URLs
+ * over named buckets (S3, R2, or local disk in development).
+ *
+ * Private content is reachable only through signed, expiring URLs, so a
+ * function that hands one out decides who may read the file. Upload URLs carry
+ * the bucket's policy; callers do not need to re-check size or MIME type.
+ */
 export interface ContentService<TBucket extends string = string> {
     signContentKey(args: SignContentKeyArgs<TBucket>): Promise<string>;
     signURL(args: SignURLArgs): Promise<string>;

package/dist/services/credential-wire-service.d.ts

@@ -15,6 +15,15 @@ export type CredentialResolutionConfig = {
     /** Keyed by the resolved (post-alias) credential name. */
     resolutions: Record<string, CredentialResolution>;
 };
+/**
+ * Holds the credentials one invocation can see, behind `wire.getCredential`.
+ * Per-user values are loaded lazily from the `CredentialService` for the
+ * resolved pikku user; credentials the wiring marks `singleton` are always read
+ * from the deployment and never from the user's own store, so a user cannot
+ * override a deployment-owned token.
+ *
+ * @internal
+ */
 export declare class PikkuCredentialWireService {
     private credentialService?;
     private wire?;

package/dist/services/credential-wire-service.js

@@ -1,5 +1,14 @@
 import { isSecretValue } from '../classification/secret-value.js';
 import { defaultPikkuUserIdResolver } from './pikku-user-id.js';
+/**
+ * Holds the credentials one invocation can see, behind `wire.getCredential`.
+ * Per-user values are loaded lazily from the `CredentialService` for the
+ * resolved pikku user; credentials the wiring marks `singleton` are always read
+ * from the deployment and never from the user's own store, so a user cannot
+ * override a deployment-owned token.
+ *
+ * @internal
+ */
 export class PikkuCredentialWireService {
     credentialService;
     wire;

package/dist/services/deployment-service.d.ts

@@ -1,16 +1,30 @@
+/** Heartbeat timing for a {@link DeploymentService}, in milliseconds. */
 export interface DeploymentServiceConfig {
     heartbeatInterval?: number;
     heartbeatTtl?: number;
 }
+/**
+ * This deployment's identity, the endpoint other deployments reach it on, and
+ * the functions it serves (all registered functions when omitted).
+ */
 export interface DeploymentConfig {
     deploymentId: string;
     endpoint: string;
     functions?: string[];
 }
+/** Another live deployment, as found in the registry. */
 export interface DeploymentInfo {
     deploymentId: string;
     endpoint: string;
 }
+/**
+ * Service discovery for split deployments: each deployment registers the
+ * functions it serves and keeps a heartbeat, and `invoke` calls a function
+ * hosted by another deployment. An RPC whose target is not registered locally
+ * falls back to `invoke`, carrying the caller's session and trace id.
+ * Implementations ship in the database and runtime packages (Kysely, Redis,
+ * MongoDB, Cloudflare, Lambda, Azure).
+ */
 export interface DeploymentService {
     init(): Promise<void>;
     start(config: DeploymentConfig): Promise<void>;

package/dist/services/email-service.d.ts

@@ -4,6 +4,10 @@ export interface EmailTemplateReference {
     locale?: string;
     data?: Record<string, unknown>;
 }
+/**
+ * A file attached to an email, or embedded inline and referenced from the HTML
+ * by `contentId`.
+ */
 export interface EmailAttachment {
     filename: string;
     /**
@@ -26,25 +30,41 @@ export interface BaseSendEmailInput {
     subject?: string;
     attachments?: EmailAttachment[];
 }
+/** A plain-text email. */
 export interface SendTextEmailInput extends BaseSendEmailInput {
     text: string;
     html?: never;
     template?: never;
 }
+/** An HTML email, with an optional plain-text alternative. */
 export interface SendHTMLEmailInput extends BaseSendEmailInput {
     html: string;
     text?: string;
     template?: never;
 }
+/**
+ * An email rendered from a named template compiled by `pikku emails`; the
+ * subject comes from the template unless set here.
+ */
 export interface SendTemplateEmailInput extends BaseSendEmailInput {
     template: EmailTemplateReference;
     html?: never;
     text?: never;
 }
+/** Exactly one of a text body, an HTML body or a template. */
 export type SendEmailInput = SendTextEmailInput | SendHTMLEmailInput | SendTemplateEmailInput;
+/** The provider's id for the sent message, when it returns one. */
 export interface SendEmailResult {
     messageId?: string;
 }
+/**
+ * Sends email through a provider (Resend, SES, SMTP, or {@link
+ * LocalEmailService} in development), provided as the `emailService` singleton
+ * service.
+ *
+ * The input is `Safe<>`-guarded: a `SecretValue` anywhere in it fails to
+ * compile, so a vault secret cannot be mailed by accident.
+ */
 export interface EmailService {
     send<T extends SendEmailInput>(input: Safe<T>): Promise<SendEmailResult>;
 }

package/dist/services/email-template.d.ts

@@ -14,6 +14,10 @@ export interface EmailTemplateHashes {
     subjectHash: string;
     textHash: string;
 }
+/**
+ * One compiled template: its HTML, subject and text sources, the variables it
+ * reads, and per-locale content hashes.
+ */
 export interface EmailTemplateAssets {
     html: string;
     subject: string;
@@ -21,17 +25,25 @@ export interface EmailTemplateAssets {
     variables: ReadonlyArray<string>;
     hashes: Record<string, EmailTemplateHashes>;
 }
+/**
+ * Everything `pikku emails` generates for rendering: the theme, locale strings,
+ * partials and templates.
+ */
 export interface EmailAssets {
     theme: Record<string, unknown>;
     locales: Record<string, Record<string, unknown>>;
     partials: Record<string, string>;
     templates: Record<string, EmailTemplateAssets>;
 }
+/**
+ * Which template to render, in which locale (default `en`), with which data.
+ */
 export interface RenderEmailRequest {
     name: string;
     locale?: string;
     data?: Record<string, unknown>;
 }
+/** A rendered email ready to send. */
 export interface RenderedEmailResult {
     locale: string;
     subject: string;
@@ -40,4 +52,16 @@ export interface RenderedEmailResult {
     variables: ReadonlyArray<string>;
     hash: string;
 }
+/**
+ * Renders a template from the generated email assets. Normally called through
+ * the typed wrapper in `pikku-emails.gen.ts`.
+ *
+ * `{{ value }}` is HTML-escaped in the HTML body; `{{{ value }}}` is written
+ * raw. Theme and locale strings (`theme.*`, `t.*`) are trusted and may contain
+ * placeholders of their own; caller data is substituted in a single pass and
+ * never re-read as a template, so it cannot inject markup or further
+ * placeholders.
+ *
+ * @throws Error when the template or the locale is unknown
+ */
 export declare const renderEmail: ({ theme, locales, partials, templates }: EmailAssets, { name, locale: requestedLocale, data }: RenderEmailRequest) => RenderedEmailResult;

package/dist/services/email-template.js

@@ -100,6 +100,18 @@ const renderTemplate = (source, partials, context, escape, slot) => {
     const composed = expandTrusted(expandPartials(source, partials), context, escape);
     return substitute(composed, context, escape, slot);
 };
+/**
+ * Renders a template from the generated email assets. Normally called through
+ * the typed wrapper in `pikku-emails.gen.ts`.
+ *
+ * `{{ value }}` is HTML-escaped in the HTML body; `{{{ value }}}` is written
+ * raw. Theme and locale strings (`theme.*`, `t.*`) are trusted and may contain
+ * placeholders of their own; caller data is substituted in a single pass and
+ * never re-read as a template, so it cannot inject markup or further
+ * placeholders.
+ *
+ * @throws Error when the template or the locale is unknown
+ */
 export const renderEmail = ({ theme, locales, partials, templates }, { name, locale: requestedLocale, data }) => {
     const locale = requestedLocale ?? 'en';
     const template = templates[name];

package/dist/services/file-scenario-run-store.d.ts

@@ -1,7 +1,12 @@
 import type { ScenarioArtifact, ScenarioResult, ScenarioRunRecord, ScenarioRunStore, ScenarioRunSummary } from '../wirings/workflow/scenario-run.types.js';
 /** Counts and duration, derived rather than stored so they cannot disagree. */
 export declare const scenarioRunSummary: (record: ScenarioRunRecord) => ScenarioRunSummary;
+/**
+ * The MIME type a scenario artifact is served with, from its file extension.
+ * Unknown extensions are served as `application/octet-stream`.
+ */
 export declare const scenarioArtifactContentType: (path: string) => string;
+/** Options for {@link FileScenarioRunStore}. */
 export interface FileScenarioRunStoreOptions {
     /** The directory runs live under — one folder per run, named by its id. */
     dir: string;

package/dist/services/file-scenario-run-store.js

@@ -43,6 +43,10 @@ const CONTENT_TYPES = {
     mp4: 'video/mp4',
     webm: 'video/webm',
 };
+/**
+ * The MIME type a scenario artifact is served with, from its file extension.
+ * Unknown extensions are served as `application/octet-stream`.
+ */
 export const scenarioArtifactContentType = (path) => CONTENT_TYPES[path.split('.').pop()?.toLowerCase() ?? ''] ??
     'application/octet-stream';
 /**

package/dist/services/gateway-service.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Starts and stops the listener gateways (long-lived connections such as a
+ * chat-platform socket) registered with `wireGateway`. {@link
+ * LocalGatewayService} runs them in the current process.
+ */
 export interface GatewayService {
     start(): Promise<void>;
     stop(): Promise<void>;

package/dist/services/in-memory-agent-run-state-service.d.ts

@@ -1,6 +1,11 @@
 import type { AgentRunStateService, CreateRunInput, SaveScoreInput } from './agent-run-state-service.js';
 import type { AgentRunState, PendingApproval } from '../wirings/agent/agent.types.js';
 import type { AgentRunScore } from '../wirings/agent-scorer/agent-scorer.types.js';
+/**
+ * An {@link AgentRunStateService} held in process memory, for development and
+ * tests. Runs are lost on restart and not shared between processes, so a run
+ * paused for approval cannot be resumed elsewhere.
+ */
 export declare class InMemoryAgentRunStateService implements AgentRunStateService {
     private runs;
     private scores;

package/dist/services/in-memory-agent-run-state-service.js

@@ -1,3 +1,8 @@
+/**
+ * An {@link AgentRunStateService} held in process memory, for development and
+ * tests. Runs are lost on restart and not shared between processes, so a run
+ * paused for approval cannot be resumed elsewhere.
+ */
 export class InMemoryAgentRunStateService {
     runs = new Map();
     scores = new Map();

package/dist/services/in-memory-lease-service.d.ts

@@ -1,4 +1,9 @@
 import type { Lease, LeaseService } from './lease-service.js';
+/**
+ * A {@link LeaseService} held in process memory, for development and tests.
+ * Leases exclude holders in this process only. The clock can be injected for
+ * tests.
+ */
 export declare class InMemoryLeaseService implements LeaseService {
     private now;
     private leases;

package/dist/services/in-memory-lease-service.js

@@ -1,3 +1,8 @@
+/**
+ * A {@link LeaseService} held in process memory, for development and tests.
+ * Leases exclude holders in this process only. The clock can be injected for
+ * tests.
+ */
 export class InMemoryLeaseService {
     now;
     leases = new Map();

package/dist/services/in-memory-session-store.d.ts

@@ -1,5 +1,9 @@
 import type { CoreUserSession } from '../types/core.types.js';
 import type { SessionStore } from './session-store.js';
+/**
+ * A {@link SessionStore} held in process memory, for development and tests.
+ * Sessions are lost on restart and not shared between processes.
+ */
 export declare class InMemorySessionStore<UserSession extends CoreUserSession = CoreUserSession> implements SessionStore<UserSession> {
     private sessions;
     get(pikkuUserId: string): Promise<UserSession | undefined>;

package/dist/services/in-memory-session-store.js

@@ -1,3 +1,7 @@
+/**
+ * A {@link SessionStore} held in process memory, for development and tests.
+ * Sessions are lost on restart and not shared between processes.
+ */
 export class InMemorySessionStore {
     sessions = new Map();
     async get(pikkuUserId) {

package/dist/services/incoming-webhook-queue.d.ts

@@ -0,0 +1,2 @@
+/** The queue every verified incoming webhook is enqueued on for its trigger. */
+export declare const PIKKU_INCOMING_WEBHOOK_QUEUE_NAME = "pikku-incoming-webhooks";

package/dist/services/incoming-webhook-queue.js

@@ -0,0 +1,2 @@
+/** The queue every verified incoming webhook is enqueued on for its trigger. */
+export const PIKKU_INCOMING_WEBHOOK_QUEUE_NAME = 'pikku-incoming-webhooks';

package/dist/services/incoming-webhook-service.d.ts

@@ -1,9 +1,17 @@
 import type { QueueService } from '../wirings/queue/queue.types.js';
-import { type TriggerEvent, type WebhookRequest, type WebhookSourceJob } from '../wirings/trigger/webhook-source.types.js';
+import type { TriggerEvent, WebhookRequest, WebhookSourceJob } from '../wirings/trigger/webhook-source.types.js';
+/**
+ * One dispatch of a received webhook event to a trigger, and the error if it
+ * failed.
+ */
 export type IncomingWebhookAttempt = {
     trigger: string;
     error?: string;
 };
+/**
+ * A received webhook event as a store-backed {@link IncomingWebhookService}
+ * records it.
+ */
 export type IncomingWebhookReceiptRecord = {
     receiptId: string;
     source: string;

package/dist/services/incoming-webhook-service.js

@@ -1,5 +1,5 @@
 import { DEFAULT_WEBHOOK_RETRIES } from './webhook-service.js';
-import { PIKKU_INCOMING_WEBHOOK_QUEUE_NAME, } from '../wirings/trigger/webhook-source.types.js';
+import { PIKKU_INCOMING_WEBHOOK_QUEUE_NAME } from './incoming-webhook-queue.js';
 /**
  * Queues each event a webhook source received for the
  * `pikku-incoming-webhooks` worker, so the provider is answered once the event

package/dist/services/index.d.ts

@@ -11,17 +11,13 @@ export { LocalEmailService } from './local-email-service.js';
 export { LocalCredentialService } from './local-credential-service.js';
 export { LocalVariablesService } from './local-variables.js';
 export { ConsoleLogger, JsonConsoleLogger } from './logger-console.js';
-export { InMemoryWorkflowService } from './in-memory-workflow-service.js';
 export { QueueWebhookService, pikkuWebhookWorkerFunc, } from './queue-webhook-service.js';
 export { IncomingWebhookService, type IncomingWebhookAttempt, type IncomingWebhookReceiptRecord, } from './incoming-webhook-service.js';
-export { REMOTE_JOBS_SECRET_HEADER, REMOTE_JOBS_SECRET_VARIABLE, REMOTE_QUEUE_JOB_PATH, REMOTE_SCHEDULER_JOB_PATH, pikkuRemoteQueueJobFunc, pikkuRemoteScheduledJobFunc, type RemoteQueueJobData, type RemoteScheduledJobData, } from './remote-jobs.js';
-export { InMemoryQueueService } from './in-memory-queue-service.js';
-export { InMemoryTriggerService } from './in-memory-trigger-service.js';
+export { REMOTE_JOBS_SECRET_HEADER, REMOTE_JOBS_SECRET_VARIABLE, REMOTE_QUEUE_JOB_PATH, REMOTE_SCHEDULER_JOB_PATH, type RemoteQueueJobData, type RemoteScheduledJobData, } from './remote-jobs.js';
 export { InMemoryTriggerSourceStore, type DeclaredTriggerSource, type TriggerSourceKind, type TriggerSourceResult, type TriggerSourceRow, type TriggerSourceStore, } from './trigger-source-store.js';
 export { LeaseLostError, LeaseTakenError, holdLease, type Lease, type LeaseService, } from './lease-service.js';
 export { InMemoryLeaseService } from './in-memory-lease-service.js';
 export { InMemoryAgentRunStateService } from './in-memory-agent-run-state-service.js';
-export { LocalGatewayService } from './local-gateway-service.js';
 export type { ContentService, ContentVisibility, GetDownloadURLArgs, SignContentKeyArgs, SignURLArgs, GetUploadURLArgs, UploadURLResult, BucketKeyArgs, WriteFileArgs, CopyFileArgs, } from './content-service.js';
 export type { ScenarioVirtualUser, ResolvedVirtualUser, ScenarioVirtualUsers, } from './virtual-users-service.js';
 export type { JWTService } from './jwt-service.js';

package/dist/services/index.js

@@ -11,17 +11,13 @@ export { LocalEmailService } from './local-email-service.js';
 export { LocalCredentialService } from './local-credential-service.js';
 export { LocalVariablesService } from './local-variables.js';
 export { ConsoleLogger, JsonConsoleLogger } from './logger-console.js';
-export { InMemoryWorkflowService } from './in-memory-workflow-service.js';
 export { QueueWebhookService, pikkuWebhookWorkerFunc, } from './queue-webhook-service.js';
 export { IncomingWebhookService, } from './incoming-webhook-service.js';
-export { REMOTE_JOBS_SECRET_HEADER, REMOTE_JOBS_SECRET_VARIABLE, REMOTE_QUEUE_JOB_PATH, REMOTE_SCHEDULER_JOB_PATH, pikkuRemoteQueueJobFunc, pikkuRemoteScheduledJobFunc, } from './remote-jobs.js';
-export { InMemoryQueueService } from './in-memory-queue-service.js';
-export { InMemoryTriggerService } from './in-memory-trigger-service.js';
+export { REMOTE_JOBS_SECRET_HEADER, REMOTE_JOBS_SECRET_VARIABLE, REMOTE_QUEUE_JOB_PATH, REMOTE_SCHEDULER_JOB_PATH, } from './remote-jobs.js';
 export { InMemoryTriggerSourceStore, } from './trigger-source-store.js';
 export { LeaseLostError, LeaseTakenError, holdLease, } from './lease-service.js';
 export { InMemoryLeaseService } from './in-memory-lease-service.js';
 export { InMemoryAgentRunStateService } from './in-memory-agent-run-state-service.js';
-export { LocalGatewayService } from './local-gateway-service.js';
 export { renderEmail, } from './email-template.js';
 export { DEFAULT_WEBHOOK_RETRIES, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, } from './webhook-service.js';
 export { VIRTUAL_USER_IN_PROCESS_ENDPOINT, VIRTUAL_USER_STATEMENT_ALGORITHM, VIRTUAL_USER_STATEMENT_MAX_TTL_SECONDS, VIRTUAL_USER_STATEMENT_TTL_SECONDS, VIRTUAL_USER_SIGNING_KEY_VARIABLE, VIRTUAL_USER_VERIFY_KEY_VARIABLE, VirtualUserStatementError, } from './virtual-user-statement.js';

package/dist/services/jwt-service.d.ts

@@ -1,4 +1,12 @@
 import type { RelativeTimeInput } from '../time-utils.js';
+/**
+ * Signs and verifies JSON Web Tokens, provided as the `jwt` singleton service
+ * (for example `@pikku/jose`). The cookie and bearer auth middleware use it to
+ * turn a token into a session.
+ *
+ * `decode` must reject a token whose signature does not verify or that has
+ * expired; it is the only check between a forged token and a session.
+ */
 export interface JWTService {
     encode: <T extends any>(expiresIn: RelativeTimeInput, payload: T) => Promise<string>;
     /** `invalidHashError` replaces the implementation's own error when the hash does not verify. */

package/dist/services/lease-service.d.ts

@@ -1,3 +1,7 @@
+/**
+ * A held lease. `token` increases each time the key changes hands, so a stale
+ * holder can be told apart from the current one.
+ */
 export type Lease = {
     key: string;
     holder: string;
@@ -16,6 +20,7 @@ export interface LeaseService {
     release(lease: Lease): Promise<void>;
     get(key: string): Promise<Lease | null>;
 }
+/** Thrown by `holdLease` when another holder already has the key. */
 export declare class LeaseTakenError extends Error {
     readonly key: string;
     constructor(key: string);

package/dist/services/lease-service.js

@@ -1,3 +1,4 @@
+/** Thrown by `holdLease` when another holder already has the key. */
 export class LeaseTakenError extends Error {
     key;
     constructor(key) {

package/dist/services/local-content-request-handler.d.ts

@@ -16,6 +16,11 @@ import { type LocalContentConfig } from './local-content.js';
  * signal to carry on with its normal routing.
  */
 export type LocalContentRequestHandler = (request: Request) => Promise<Response | null>;
+/**
+ * Options for {@link createLocalContentRequestHandler}. `content` must match
+ * the config the {@link LocalContent} service was built with, and `getJWT` must
+ * return the same `JWTService` it signs with.
+ */
 export type LocalContentRequestHandlerOptions = {
     content: LocalContentConfig;
     logger: Logger;
@@ -26,6 +31,10 @@ export type LocalContentRequestHandlerOptions = {
      */
     getJWT: () => JWTService | undefined;
 };
+/**
+ * The verdict of {@link verifySignedContentRequest}: either valid, or the
+ * status and body to refuse the request with.
+ */
 export type SignedContentVerification = {
     ok: true;
 } | {
@@ -47,4 +56,15 @@ export type SignedContentVerification = {
  * invalid, never as trusted.
  */
 export declare const verifySignedContentRequest: (requestUrl: URL, jwt: JWTService | undefined, onMissingJWT?: () => void) => Promise<SignedContentVerification>;
+/**
+ * Creates the request handler that serves {@link LocalContent}: signed `PUT`
+ * uploads under `uploadUrlPrefix`, and `GET`/`HEAD` reads under
+ * `assetUrlPrefix`.
+ *
+ * Uploads always require a valid signature; reads require one unless the file
+ * is public. Paths that escape the content root are refused with 400, and
+ * uploads over `sizeLimit` (default `1mb`) with 413. When no `JWTService` is
+ * available, every signed request is refused and the misconfiguration is logged
+ * once.
+ */
 export declare const createLocalContentRequestHandler: ({ content, logger, getJWT, }: LocalContentRequestHandlerOptions) => LocalContentRequestHandler;

package/dist/services/local-content-request-handler.js

@@ -64,6 +64,17 @@ export const verifySignedContentRequest = async (requestUrl, jwt, onMissingJWT)
     }
     return { ok: true };
 };
+/**
+ * Creates the request handler that serves {@link LocalContent}: signed `PUT`
+ * uploads under `uploadUrlPrefix`, and `GET`/`HEAD` reads under
+ * `assetUrlPrefix`.
+ *
+ * Uploads always require a valid signature; reads require one unless the file
+ * is public. Paths that escape the content root are refused with 400, and
+ * uploads over `sizeLimit` (default `1mb`) with 413. When no `JWTService` is
+ * available, every signed request is refused and the misconfiguration is logged
+ * once.
+ */
 export const createLocalContentRequestHandler = ({ content, logger, getJWT, }) => {
     // Logged at most once. An unverifiable request is attacker-triggerable, so
     // this reports a startup misconfiguration rather than per-request news.

package/dist/services/local-content.d.ts

@@ -1,4 +1,9 @@
 import type { BucketKeyArgs, ContentService, ContentVisibility, GetDownloadURLArgs, CopyFileArgs, GetUploadURLArgs, JWTService, Logger, SignContentKeyArgs, SignURLArgs, UploadURLResult, WriteFileArgs } from '@pikku/core/services';
+/**
+ * Configuration for {@link LocalContent}: the directory files are stored in,
+ * the URL prefixes uploads and reads are served under, the origin to prefix
+ * URLs with, and the largest accepted upload (for example `10mb`).
+ */
 export interface LocalContentConfig {
     localFileUploadPath: string;
     uploadUrlPrefix: string;
@@ -17,8 +22,20 @@ export interface LocalContentConfig {
  * rather than throwing, which keeps both sides in agreement.
  */
 export declare const signedContentPath: (urlOrPath: string) => string;
+/**
+ * The leading URL segment that marks public content. A private bucket cannot
+ * use this name.
+ */
 export declare const PUBLIC_URL_SEGMENT = "_public";
+/**
+ * Every {@link ContentVisibility}, also the names of the two directories under
+ * the content root.
+ */
 export declare const CONTENT_VISIBILITIES: readonly ContentVisibility[];
+/**
+ * A content URL path split into the visibility it names and the
+ * `<bucket>/<key>` remainder.
+ */
 export type ContentUrlPath = {
     visibility: ContentVisibility;
     rest: string;
@@ -37,6 +54,7 @@ export declare const parseContentUrlPath: (key: string) => ContentUrlPath;
  * inside it, so neither side can climb out or reach the other.
  */
 export declare const resolveVisibilityPath: (basePath: string, visibility: ContentVisibility, bucket: string, key: string) => string | null;
+/** The file a content request resolves to, and whether it is public. */
 export type ContentRequestTarget = {
     path: string;
     visibility: ContentVisibility;
@@ -50,11 +68,38 @@ export type ContentRequestTarget = {
  * check only when the result is public.
  */
 export declare const resolveContentRequestTarget: (basePath: string, key: string, mode: 'read' | 'write') => Promise<ContentRequestTarget | null>;
+/**
+ * Thrown by {@link streamUploadToFile} when an upload passes its byte limit.
+ */
 export declare class UploadTooLargeError extends Error {
     constructor();
 }
+/**
+ * Parses a size such as `512kb` or `10mb` (binary units; no unit means bytes)
+ * into bytes.
+ *
+ * @throws Error when the string is not a size
+ */
 export declare const parseContentSizeLimit: (sizeLimit: string) => number;
+/**
+ * Streams an upload to `targetPath`, writing to a temporary file that is
+ * renamed into place only once the whole body arrived, so a failed or oversized
+ * upload never leaves a partial file behind.
+ *
+ * @returns the number of bytes written
+ * @throws UploadTooLargeError when the body passes `maxBytes`
+ */
 export declare const streamUploadToFile: (source: AsyncIterable<Uint8Array>, targetPath: string, maxBytes: number) => Promise<number>;
+/**
+ * A {@link ContentService} that stores files on local disk, for development and
+ * single-server deployments. Private and public files live in separate
+ * directories; URLs for private files are signed with the given `JWTService`
+ * and checked by {@link createLocalContentRequestHandler}, and upload URLs
+ * expire after 15 minutes. Keys that would escape the content root are
+ * rejected.
+ *
+ * @throws Error from the constructor when no `JWTService` is given
+ */
 export declare class LocalContent implements ContentService {
     private config;
     private logger;