@workwae/sdk 0.0.0-stage → 0.1.0-alpha.1

package/contract/errors.d.ts

@@ -0,0 +1,108 @@
+import { type ErrorReason, type ReasonDataSchema, type ReasonStatus, type ReasonTable } from "./reasons.js";
+/** A declared error: its reason's status and data schema, with the condition as its message. */
+export type DeclaredError<R extends ErrorReason> = {
+    status: ReasonStatus<R>;
+    message: string;
+} & (ReasonDataSchema<R> extends undefined ? unknown : {
+    data: ReasonDataSchema<R>;
+});
+export type DeclaredErrors<C> = {
+    [R in keyof C & ErrorReason]: DeclaredError<R>;
+};
+/**
+ * The oRPC error map for `conditions` (reason -> when it is answered, one sentence), each with its
+ * reason's status and data schema from `table`. errors() below and the console's wrap it; they
+ * are declared functions with named return types so declarations reference the table by name
+ * instead of inlining it into every route.
+ */
+export declare function errorMap(table: ReasonTable, conditions: Record<string, string | undefined>): Record<string, {
+    status: number;
+    message: string;
+    data?: unknown;
+}>;
+/** The error map of a /v1 route; console routes use console/reasons.ts's, which knows theirs. */
+export declare function errors<const C extends {
+    [R in ErrorReason]?: string;
+}>(conditions: C): DeclaredErrors<C>;
+/** What any route can answer with, whoever calls it and whatever it does. */
+export declare const GLOBAL_ERRORS: DeclaredErrors<{
+    readonly invalid_input: "The request does not match the operation's input schema (a malformed body included); data.issues names each problem.";
+    readonly unauthenticated: "No usable credential: none was sent, or it is malformed, unknown, revoked or an expired account token.";
+    readonly api_key_expired: "The API key is past its expiry (or the grace of the rotation that replaced it).";
+    readonly missing_scope: "The API key lacks the scope the operation needs.";
+    readonly role_forbidden: "The member's role does not allow the operation.";
+    readonly account_token_forbidden: "An account token called an operation account tokens cannot call.";
+    readonly rate_limited: "The tenant used up its plan's request rate; Retry-After says when the window ends.";
+    readonly too_many_requests: "The credential has too many requests in flight at once; retry after Retry-After.";
+    readonly overloaded: "The API is shedding load; retry after Retry-After.";
+    readonly payload_too_large: "The request body is larger than the API accepts.";
+    readonly internal_error: "An unexpected failure on our side.";
+    readonly invalid_idempotency_key: "POST only: the Idempotency-Key header is not 1 to 255 printable ASCII characters.";
+    readonly idempotency_key_reused: "POST only: the Idempotency-Key was used in the last 24 hours with another method, path or body.";
+    readonly idempotency_key_in_progress: "POST only: the request first sent with this Idempotency-Key has not been answered yet.";
+}>;
+/** The builder every route starts from: oc with GLOBAL_ERRORS declared. */
+export declare const base: import("@orpc/contract").ContractBuilder<import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").MergedErrorMap<Record<never, never>, DeclaredErrors<{
+    readonly invalid_input: "The request does not match the operation's input schema (a malformed body included); data.issues names each problem.";
+    readonly unauthenticated: "No usable credential: none was sent, or it is malformed, unknown, revoked or an expired account token.";
+    readonly api_key_expired: "The API key is past its expiry (or the grace of the rotation that replaced it).";
+    readonly missing_scope: "The API key lacks the scope the operation needs.";
+    readonly role_forbidden: "The member's role does not allow the operation.";
+    readonly account_token_forbidden: "An account token called an operation account tokens cannot call.";
+    readonly rate_limited: "The tenant used up its plan's request rate; Retry-After says when the window ends.";
+    readonly too_many_requests: "The credential has too many requests in flight at once; retry after Retry-After.";
+    readonly overloaded: "The API is shedding load; retry after Retry-After.";
+    readonly payload_too_large: "The request body is larger than the API accepts.";
+    readonly internal_error: "An unexpected failure on our side.";
+    readonly invalid_idempotency_key: "POST only: the Idempotency-Key header is not 1 to 255 printable ASCII characters.";
+    readonly idempotency_key_reused: "POST only: the Idempotency-Key was used in the last 24 hours with another method, path or body.";
+    readonly idempotency_key_in_progress: "POST only: the request first sent with this Idempotency-Key has not been answered yet.";
+}>>, Record<never, never>>;
+export declare const SESSION_ONLY: DeclaredErrors<{
+    readonly session_required: "The caller is not a board session (only board sessions may call this).";
+}>;
+export declare const OWNER_ONLY: DeclaredErrors<{
+    readonly session_required: "The caller is not a board session (only board sessions may call this).";
+    readonly owner_required: "The caller does not own the organization.";
+}>;
+export declare const PLATFORM_ONLY: DeclaredErrors<{
+    readonly session_required: "The caller is not a board session (only board sessions may call this).";
+    readonly platform_admin_required: "The caller is not a platform administrator.";
+    readonly email_verification_required: "The platform administrator has not verified their email address yet.";
+}>;
+/** The account a path names: missing, deleted, or another account than an account token's. */
+export declare const ACCOUNT_NOT_FOUND: DeclaredErrors<{
+    readonly account_not_found: "The account does not exist, or the caller is an account token for another account.";
+}>;
+/** The account states that keep a route from reaching the provider; `account` names the account
+ * and may narrow when, e.g. "With source=provider, the account". */
+export declare function accountState(account?: string): DeclaredErrors<{
+    readonly account_paused: `${string} is paused.`;
+    readonly account_disabled: `${string} is disabled.`;
+    readonly account_reauth_required: `${string} must be reconnected: its stored grant or login no longer works.`;
+    readonly account_misconfigured: `${string}'s stored grant cannot be used until an administrator fixes what it relies on (the tenant's OAuth app or organization connection is refused, missing or unreadable).`;
+}>;
+/** What any provider call answers when it fails. A route the provider can refuse adds
+ * `provider_forbidden` with its own condition, and one reading an item `provider_not_found`. */
+export declare const PROVIDER_FAILURES: DeclaredErrors<{
+    readonly provider_throttled: "The provider asked us to slow down (with Retry-After when it named a wait).";
+    readonly provider_unavailable: "The provider could not be reached (with Retry-After when it named a wait).";
+}>;
+/** What asking for stored bodies through `field` refuses. */
+export declare function bodyStorage(field: string): DeclaredErrors<{
+    readonly storage_unavailable: `${string} is cache or full and no object store is configured.`;
+    readonly plan_limit_storage: `${string} is cache or full and the tenant's plan does not include body storage.`;
+}>;
+/** A route of a module the tenant's plan may lack, e.g. planModule("calendar"). */
+export declare function planModule(module: string): DeclaredErrors<{
+    readonly plan_module_unavailable: `The tenant's plan does not include ${string}.`;
+}>;
+export declare const PLAN_LIMIT_ACCOUNTS: DeclaredErrors<{
+    readonly plan_limit_accounts: "The tenant already has as many accounts as its plan allows.";
+}>;
+export declare const BILLING_PAST_DUE: DeclaredErrors<{
+    readonly billing_past_due: "The tenant's payment is past due beyond the grace period (sends already queued or scheduled still go out).";
+}>;
+export declare const INVALID_CURSOR: DeclaredErrors<{
+    readonly invalid_cursor: "The cursor is not one this list issued.";
+}>;