@pikku/core 0.12.143 → 0.12.144

package/dist/errors/error-handler.js

@@ -1,4 +1,12 @@
 import { pikkuState } from '../pikku-state.js';
+/**
+ * Base class for errors a function throws on purpose. Subclass it and register
+ * the subclass with {@link addError} to choose the status and message the
+ * caller gets; an unregistered error answers 500. `name` is set to the
+ * subclass's name, and {@link isExpectedError} treats every `PikkuError` as
+ * expected, so it is logged by message rather than with a stack trace.
+ * @group Error
+ */
 export class PikkuError extends Error {
     constructor(message = 'An error occurred') {
         super(message);

package/dist/errors/errors.d.ts

@@ -1,24 +1,86 @@
 import { PikkuError } from './error-handler.js';
+/**
+ * A middleware was attached to a wiring type it cannot run on. Answers 500.
+ * @group Error
+ */
 export declare class InvalidMiddlewareWireError extends PikkuError {
 }
+/**
+ * The generated metadata for a wiring (a queue worker, trigger, workflow, …) is
+ * missing at runtime, usually because `pikku` codegen was not re-run after a
+ * change. Answers 500.
+ * @group Error
+ */
 export declare class PikkuMissingMetaError extends PikkuError {
 }
+/**
+ * A function needed a service that was not created in your singleton or wire
+ * services factory. Answers 500.
+ * @group Error
+ */
 export declare class MissingServiceError extends PikkuError {
 }
+/**
+ * A development-only operation was called outside local development. Answers
+ * 403.
+ * @group Error
+ */
 export declare class LocalEnvironmentOnlyError extends PikkuError {
 }
+/**
+ * The request is malformed or its data failed validation. Answers 400 (JSON-RPC
+ * `-32600` over MCP).
+ * @group Error
+ */
 export declare class BadRequestError extends PikkuError {
 }
+/**
+ * Authentication was attempted and failed for a reason that is not about the
+ * session itself, such as a bad webhook signature or dispatch secret. Answers
+ * 401.
+ * @group Error
+ */
 export declare class UnauthorizedError extends PikkuError {
 }
+/**
+ * No session was resolved for a function that requires one: either a
+ * `pikkuFunc`, or a sessionless function wired or configured with
+ * `auth: true`. Answers 401 — the caller has to sign in. Contrast
+ * {@link InvalidSessionError} (credentials were sent but are not valid) and
+ * {@link ForbiddenError} (signed in, but not allowed).
+ * @group Error
+ */
 export declare class MissingSessionError extends PikkuError {
 }
+/**
+ * Credentials were presented but could not be turned into a session, for
+ * example an `Authorization` header that is not a well-formed `Bearer` token.
+ * Answers 401; the caller should re-authenticate rather than retry.
+ * @group Error
+ */
 export declare class InvalidSessionError extends PikkuError {
 }
+/**
+ * The operation needs a paid plan or payment. Answers 402.
+ * @group Error
+ */
 export declare class PaymentRequiredError extends PikkuError {
 }
+/**
+ * The caller is authenticated but a permission (global, wiring or function
+ * level) refused the call. Answers 403 — signing in again will not help.
+ * Authentication failures are {@link MissingSessionError} and
+ * {@link InvalidSessionError} instead.
+ * @group Error
+ */
 export declare class ForbiddenError extends PikkuError {
 }
+/**
+ * A function needs a per-user credential (OAuth2 or API key) that the user has
+ * not connected yet. Answers 403; `payload` names the credential and, when
+ * known, the `connectUrl` the client should send the user to.
+ * @group Error
+ */
 export declare class MissingCredentialError extends PikkuError {
     payload: {
         error: 'missing_credential';
@@ -28,6 +90,11 @@ export declare class MissingCredentialError extends PikkuError {
     };
     constructor(credentialName: string, credentialType: 'oauth2' | 'apikey', connectUrl?: string);
 }
+/**
+ * The upstream service refused a stored credential. Answers 403; `payload.reauth`
+ * says whether the user has to sign in again or reconnect the credential.
+ * @group Error
+ */
 export declare class CredentialRejectedError extends PikkuError {
     payload: {
         error: 'credential_rejected';
@@ -36,6 +103,11 @@ export declare class CredentialRejectedError extends PikkuError {
     };
     constructor(credentialName: string, reauth: 'sign-in' | 'connect', message?: string);
 }
+/**
+ * The session does not hold a scope the function (or the addon running it)
+ * requires. Answers 403; `payload.scope` names the missing scope.
+ * @group Error
+ */
 export declare class MissingScopeError extends PikkuError {
     payload: {
         error: 'missing_scope';
@@ -43,6 +115,12 @@ export declare class MissingScopeError extends PikkuError {
     };
     constructor(scope: string);
 }
+/**
+ * A feature flag guarding the function is switched off. Answers 503, so the
+ * caller treats it as temporary and retryable rather than as a permission
+ * problem; `payload.feature` names the flag.
+ * @group Error
+ */
 export declare class FeatureUnavailableError extends PikkuError {
     payload: {
         error: 'feature_unavailable';
@@ -50,66 +128,207 @@ export declare class FeatureUnavailableError extends PikkuError {
     };
     constructor(feature: string);
 }
+/**
+ * A session with `readonly: true` called a function that is not declared
+ * `readonly`. Answers 403.
+ * @group Error
+ */
 export declare class ReadonlySessionError extends PikkuError {
 }
+/**
+ * The request's `Origin` is not on the allowlist of the `requireOrigin`
+ * middleware, the CSRF guard for cookie-authenticated routes. Answers 403.
+ * @group Error
+ */
 export declare class InvalidOriginError extends PikkuError {
 }
+/**
+ * The requested resource does not exist. Answers 404 (JSON-RPC `-32601` over
+ * MCP).
+ * @group Error
+ */
 export declare class NotFoundError extends PikkuError {
 }
+/**
+ * The resource exists but does not accept this HTTP method. Answers 405.
+ * @group Error
+ */
 export declare class MethodNotAllowedError extends PikkuError {
 }
+/**
+ * No representation matches the request's `Accept` headers. Answers 406.
+ * @group Error
+ */
 export declare class NotAcceptableError extends PikkuError {
 }
+/**
+ * Authentication with a proxy is required. Answers 407.
+ * @group Error
+ */
 export declare class ProxyAuthenticationRequiredError extends PikkuError {
 }
+/**
+ * The request took too long to arrive. Answers 408.
+ * @group Error
+ */
 export declare class RequestTimeoutError extends PikkuError {
 }
+/**
+ * The request conflicts with the current state of the resource, such as a
+ * duplicate or a stale write. Answers 409.
+ * @group Error
+ */
 export declare class ConflictError extends PikkuError {
 }
+/**
+ * The resource existed but has been permanently removed. Answers 410.
+ * @group Error
+ */
 export declare class GoneError extends PikkuError {
 }
+/**
+ * The request has no `Content-Length` and one is required. Answers 411.
+ * @group Error
+ */
 export declare class LengthRequiredError extends PikkuError {
 }
+/**
+ * A conditional request header (`If-Match`, …) did not hold. Answers 412.
+ * @group Error
+ */
 export declare class PreconditionFailedError extends PikkuError {
 }
+/**
+ * The request body exceeds the configured maximum body size; the HTTP request
+ * adapters throw it while reading the body. Answers 413.
+ * @group Error
+ */
 export declare class PayloadTooLargeError extends PikkuError {
 }
+/**
+ * The request URI is longer than the server accepts. Answers 414.
+ * @group Error
+ */
 export declare class URITooLongError extends PikkuError {
 }
+/**
+ * The request body's content type is not supported. Answers 415.
+ * @group Error
+ */
 export declare class UnsupportedMediaTypeError extends PikkuError {
 }
+/**
+ * The requested byte range cannot be served. Answers 416.
+ * @group Error
+ */
 export declare class RangeNotSatisfiableError extends PikkuError {
 }
+/**
+ * The `Expect` request header cannot be met. Answers 417.
+ * @group Error
+ */
 export declare class ExpectationFailedError extends PikkuError {
 }
+/**
+ * The request is well-formed but semantically invalid. Answers 422.
+ * @group Error
+ */
 export declare class UnprocessableContentError extends PikkuError {
 }
+/**
+ * The resource is locked. Answers 423.
+ * @group Error
+ */
 export declare class LockedError extends PikkuError {
 }
+/**
+ * The caller has been rate limited. Answers 429.
+ * @group Error
+ */
 export declare class TooManyRequestsError extends PikkuError {
 }
+/**
+ * A generic server-side failure with no more specific error. Answers 500.
+ * @group Error
+ */
 export declare class InternalServerError extends PikkuError {
 }
+/**
+ * The operation is not implemented. Answers 501.
+ * @group Error
+ */
 export declare class NotImplementedError extends PikkuError {
 }
+/**
+ * An upstream service returned an invalid response. Answers 502.
+ * @group Error
+ */
 export declare class BadGatewayError extends PikkuError {
 }
+/**
+ * The service is temporarily unavailable (overloaded or down). Answers 503.
+ * @group Error
+ */
 export declare class ServiceUnavailableError extends PikkuError {
 }
+/**
+ * An upstream service did not answer in time. Answers 504.
+ * @group Error
+ */
 export declare class GatewayTimeoutError extends PikkuError {
 }
+/**
+ * The request's HTTP version is not supported. Answers 505.
+ * @group Error
+ */
 export declare class HTTPVersionNotSupportedError extends PikkuError {
 }
+/**
+ * The function ran past the maximum compute time the runtime allows. Answers
+ * 524.
+ * @group Error
+ */
 export declare class MaxComputeTimeReachedError extends PikkuError {
 }
+/**
+ * Validation was asked for a schema that was never registered, usually because
+ * schema generation has not been run. Answers 500.
+ * @group Error
+ */
 export declare class MissingSchemaError extends PikkuError {
 }
+/**
+ * A configured secret is too short to be used as key material. Thrown at
+ * startup or first use rather than letting a guessable key sign or encrypt
+ * anything. Answers 500.
+ * @group Error
+ */
 export declare class WeakKeyMaterialError extends PikkuError {
     constructor(name: string, minimumLength: number, actualLength: number);
 }
+/**
+ * An agent was run without any AI provider service configured. Answers 503.
+ * @group Error
+ */
 export declare class AIProviderNotConfiguredError extends PikkuError {
     constructor();
 }
+/**
+ * The model answered, but not with what the agent's output schema promises.
+ * A 502 rather than a 422: the bad content came from the model, not from the
+ * caller, and resending the same request is the only remedy the caller has.
+ * @group Error
+ */
+export declare class AgentOutputValidationError extends PikkuError {
+    readonly agentName: string | undefined;
+    readonly issues: readonly string[];
+    constructor(agentName: string | undefined, issues: readonly string[]);
+}
+/**
+ * The configured AI provider rejected its API key, or none was set. Answers
+ * 401.
+ * @group Error
+ */
 export declare class AIProviderAuthError extends PikkuError {
     constructor(message?: string);
 }