@aletheia-dev/core

0.7.0

Minor Changes

• c7b166c: Self-service signup: SignupInput and SignupResult are the body and answer of POST /signup, which makes a workspace (an organisation with its admin, and a tenant) and emails the admin a temporary password. Its errors are SignupExistsError (409 signup_exists), TurnstileFailedError (403 turnstile_failed), SignupCapacityError (429 signup_capacity) and SignupUnavailableError (503 signup_unavailable). EnvSchema gains ZITADEL_SIGNUP_PAT, RESEND_API_KEY, SIGNUP_EMAIL_FROM, SIGNUP_EMAIL_REPLY_TO, SIGNUP_CONSOLE_URL, TURNSTILE_SECRET_KEY and SIGNUP_MAX_PER_HOUR.
• 6ef571a: Uploads are presigned PUTs, which every S3-compatible store serves, Cloudflare R2 among them. DocumentUploadTicket.upload is { method: 'PUT', url, headers, expiresAt }: the URL is signed for the declared Content-Type and sizeBytes, and fields and maxBytes are gone. uploadToStorage sends the file as the request body with the ticket's headers, and UploadXhr gains setRequestHeader.

Patch Changes

• 250c4b6: The package ships without source maps. Its homepage is its page on the documentation site, issues go to the support page or aletheia-dev@ajrd.net, and the changelog no longer links commits.

0.6.0

Minor Changes

• 7821afa: StaleSubmissionError (412 stale_submission): PATCH /collection-submissions/{id} with If-Match: <updatedAt> saves only over that version, and answers with the stored one in details.updatedAt otherwise. Submission links carry the token in the fragment (/flow/{id}#token=…); GET /collection-submissions/{id}/embed answers a link that expired in the last 30 days with expired: true; applicants and the public routes count against API_RATE_LIMIT_PER_MINUTE; every API response is Cache-Control: no-store unless a route sets its own.

• c9d9f77: Fields take autocomplete (AutocompleteToken, on text, email, number and date fields; a date takes bday or off) and inputMode (InputMode, on text and number fields). validateFlowBody reports hint_on_other_type. Submit validation changes for flows already published: a required checkbox must be true, and an empty string is no answer for every field type, so an optional field takes it as unanswered (an emptied optional number is no longer 0) and a required one answers "<label> is required". StepPreview shows that message as the engine words it.

• 8984323: The address guards (isPrivateAddress, webhookUrlProblem, publicOnlyLookup) move from @aletheia-dev/webhooks to @aletheia-dev/core/node; EnvSchema gains APP_CATALOG_DIR.

• 19af0f9: EnvSchema carries the app runner's settings (APP_RUNNER_URL, APP_RUNNER_TOKEN, APP_RUNNER_API_URL, APP_RUNNER_HOST, APP_RUNNER_PORT, APP_RUNNER_CONCURRENCY, APP_RUNNER_TENANT_CONCURRENCY, APP_RUNNER_CACHE_DIR, APP_RUNNER_CACHE_MODULES, APP_RUNNER_ALLOW_PRIVATE_NETWORKS).

• 0b5f8ad: The apps contract: what a module answers (AppManifest, its actions, secrets, hosts and handles; AppName, which refuses the apps API's own path segments in RESERVED_APP_NAMES), the envelopes and host requests between a module and the host, the app runner's HTTP contract (RunnerInvokeRequest and its siblings), and the platform's records: AppVersion, AppVersionApproval, AppInstall, AppCatalogEntry, AppUsage, AppInvocation, AppHealthReport, AppCallback and the AppCallbackSignal a vendor's webhook sends the waiting run. Workflows take a call_app step (CallAppStep), rules the app type and audit actors the app type; EnvSchema gains TEMPORAL_APP_TASK_QUEUE (default aletheia-apps).

• 26474ac: Plugins are gone, apps having replaced them: the plugin schemas (PluginDefinition, PluginInvocation, PluginHealthReport, PluginSummary, PluginCallback and their kin), the call_plugin step (CallPluginStep), the plugin rule and actor types, the plugin_degraded notification, the plugin.circuit.opened webhook event and TEMPORAL_PLUGIN_TASK_QUEUE are removed. The health summary, Home's attention items and setup checklist, and a case's vendor checks (VendorCheck) cover apps only.

• 729209c: The secret cipher (SecretCipher, SecretScope and the store:<id> references storeRef and storeIdOf) moves from @aletheia-dev/plugin-runtime to @aletheia-dev/core/node.

• e2bef29: CollectionSettings.locales: the languages a tenant's forms come in, as LocaleTags (BCP 47 in canonical case: fr, pt-BR, zh-Hant), the first being the one its flows are written in; collectionLocales(settings) reads them, English when unset. CollectionFlowBody.translations: the flow in other languages by tag (FlowTranslation, with StepTranslation and FieldTranslation): names, step titles and descriptions, field labels, help, placeholders, units, option labels and messages, and the welcome, thank-you and outcome copy. FlowPreview.locales carries the tenant's languages to previews. validateFlowBody warns about translations of steps (translation_unknown_step), fields (translation_unknown_field) and options (translation_unknown_option) the flow does not have.

• d40d16f: SubmissionEventInput (step_viewed with a stepId, upload_failed with a fieldKey and a lowercase reason code) and MAX_SUBMISSION_EVENTS: what the collection terminal reports to POST /collection-submissions/:id/events. FlowFunnel and FlowFunnelQuery: a flow's drop-off from GET /stats/flows/:key/funnel (opened, submitted, per step reached and stoppedHere, and uploadFailures), which the API client reads with stats.flowFunnel(key, { days }).

• 259e0b5: The webhook event submission.link_requested (from the audit action collection.submission.link_requested): an applicant whose link expired asked for a new one, carrying ids only. LinkRequestsUnavailableError (409 link_requests_unavailable) answers such a request where no enabled endpoint of the tenant takes the event.

• c05e741: File fields take several files (Field.multiple, maxFiles up to MAX_FILES_PER_FIELD, fileLimit): the answer is an array of FileFieldValue, validateSubmission takes one file to the limit when required, fileFieldValues lists each file with its index, and validateFlowBody reports file_option_on_other_type and max_files_without_multiple. Fields take capture (FileCapture) and documentKind (DocumentKind). A rejected Document carries rejectionCode (DocumentRejectionCode) beside its reason. FieldInput renders a field that takes several files with FileListField.

• e290fd4: CollectionSettings.abandonAfterDays (1 to 365): forms nobody saved for that many days expire and a run waiting for one is cancelled; a request for information keeps its own expiry.

• 75b54c5: TenantSettings.branding (TenantBranding: name, logos and their text alternative, brand color, shape, font, color scheme, support contacts, privacy, terms and return addresses; https only) and HexColor. CollectionFlowBody.presentation (FlowPresentation: the welcome screen's heading, text and minutes, and the thank-you screen) and CollectionFlowBody.outcome (FlowOutcome: OutcomeVisibility neutral, progress or decision, and the review, approved and rejected screens' ScreenCopy). FlowPreview.branding carries the tenant's branding to previews.

• 1551100: mergeBranding(defaults, tenant): a tenant's branding over the deployment's defaults, the name and logo, like the two support contacts, taken from one side only. The API environment takes the collection terminal's defaults (COLLECTION_TERMINAL_TENANT_NAME, _LOGO_URL, _PRIMARY_COLOR, _COLOR_SCHEME, _SUPPORT_URL, _SUPPORT_EMAIL, _PRIVACY_URL, _TERMS_URL, _RETURN_URL, _SHOW_DECISION; an empty value is unset), read with defaultBrandingOf(env).

• 78c68ac: An app whose asynchronous action starts a session the applicant takes part in (a liveness check, documents the vendor collects) declares handles.handoff (an AppHandoffSdk such as sumsub) and hands the session to the applicant's browser as an AppHandoff (sdk, a short-lived token and its expiresAt), or null once the vendor has everything. The collection terminal shows the vendor's SDK with it after the submit. HandoffUnavailableError (409 handoff_unavailable) says nothing waits for the applicant at a vendor, and SubmissionStatus.handoff is true while the run waits for such a check.

0.5.0

Minor Changes

• 4bbc905: Approvals: a requester (or an admin) withdraws an open request with POST <prefix>/{key}/versions/{version}/withdraw, which closes it as withdrawn (a new ApprovalDecision) and returns the version to draft; anyone else gets 403 not_requester (NotRequesterError). Requests carry an append-only discussion (GET/POST /approvals/{id}/comments, ApprovalComment). GET /approvals filters on status (open or decided), kind, mine and stale, pages, and returns a total (ApprovalListQuery); GET /approvals/{id} returns the request with its version, published version, diff, latest backtest, dependencies, usage, eligible approvers and discussion (ApprovalDetail). POST /backtests also takes a workflow version (StartWorkflowBacktestInput, { workflowKey, version? }): each recorded evaluation of its runs is replayed through the rule step of the same id, and the summary adds the replayed outcomes in decisions; Backtest carries workflowKey and workflowVersion, with ruleKey and ruleVersion now optional. The client replaces governance.approvals.listOpen with list and adds approvals.get, comments and comment, governance.withdraw and isNotRequester.

• 40ee302: Audit: every row written during an API request records meta (RequestMeta: request id, route, IP, user agent; TenantContext.request), included in exports as a meta column. GET /audit-events/{id} answers an AuditEventDetail: the event, its neighbors under the list filters it takes and the related case, decision, run and subject. GET /audit-events/count previews an export (AuditExportPreview). The export takes filename and trails X-Export-Rows. Saved views per user: GET, POST /audit-views, DELETE /audit-views/{id} (AuditView, AuditViewInput, AuditViewFilters). Scheduled exports: GET, POST /audit-export-schedules, GET, PUT, DELETE /audit-export-schedules/{id}, GET /audit-export-schedules/{id}/runs and POST /audit-export-runs/{id}/download (AuditExportSchedule, AuditExportScheduleInput, ScheduledExportFilter, CronExpression, AuditExportRun, AuditExportRunStatus, AuditExportDownload); AttentionItem gains export_failed. The client's audit.get takes the list filter and answers the detail, audit.count is new, audit.export and audit.exportUrl take a file name, and auditViews and auditExports are new.

• e236779: Requests for information. POST /cases/:id/request-info sends the applicant the form the case's run collected again, pre-filled, with the reviewer's message; the case waits with its SLA paused (infoRequestedAt) and the run repeats its checks on the answers before handing the case back. An unanswered request expires with the case rejected (info_not_provided). Submissions gain the withdrawn and expired statuses and caseId, requestMessage and expiresAt; operators can re-issue a link (POST /collection-submissions/:id/link) or withdraw a submission (POST /collection-submissions/:id/withdraw), and GET /collection-submissions/:id/status names the form the run waits for next. The client adds cases.requestInfo, collectionSubmissions.reissueLink and collectionSubmissions.withdraw.

• 6d17f78: Cases: GET /cases filters on queue (the routing label a run gives its case through the create_case step's queueFrom; priorityFrom sets the priority the same way), reasonCode, country and waiting, searches the subject and the case id, applies a queue with queueId and names the assignee with expand=assignee. GET /cases/{id}/evidence returns the rule hits, documents, vendor checks (with a readable resultLabel), events and decisions in one response, GET /case-types the types in use, and GET/PUT /reason-codes a reason-code catalogue that decisions are then checked against (ReasonCode, CaseEvidence, CaseType). Every tenant has the system queues; queues carry systemKey, visibility (everyone, admins, personal) and claimNext, are reordered with PUT /case-queues/order and previewed with POST /case-queues/preview, and POST /cases/claim-next {} draws from the claim-next queues. The client adds cases.evidence, types and reasonCodes, and caseQueues.reorder and preview.

• 84e50a4: Definitions: PATCH <prefix>/{key}/versions/{version} saves a draft version in place (the body PUT takes, with an optional change note; 409 once it is no longer a draft), and every definition entity and DefinitionVersionSummary carries note and updatedBy (VersionNote, VersionNoteInput). POST /rule-definitions/validate and POST /rule-sets/validate answer a ValidationReport with warnings such as list_stale and unpublished_rule. Dry runs take versions (up to 5) and answer { key, results: [{ version, status, type, result, explanation }], dataPaths } (DryRunInput, DryRunResponse); analysts with backtests:run may run them. A workflow DefinitionDiff adds steps (DiffStep). GET /definitions/usage lists what names each rule, rule set and collection flow (DefinitionUsage, UsageLink). POST /workflow-definitions/context-paths lists the run-context paths a step can read (ContextPath). POST /collection-flows/{key}/versions/{version}/preview returns a 15-minute preview link (FlowPreviewLink) that the collection terminal opens with GET /collection-flow-preview (FlowPreview). GET /definitions/packs lists the starter packs (PolicyPackSummary) and POST /definitions/import?pack= imports one. The client adds updateDraft to every definition domain, ruleDefinitions.validate, ruleSets.validate, workflowDefinitions.contextPaths, collectionFlows.preview, definitions.usage, policyPacks.starters and importStarter; dryRun takes versions.

• 6ba6815: Outbound webhooks: GET, POST /webhook-endpoints, GET, PUT, DELETE /webhook-endpoints/{id} (the signing secret is returned once), POST /webhook-endpoints/{id}/test (a signed ping), POST /webhook-endpoints/{id}/rotate-secret (the previous secret signs too for 24 hours), GET /webhook-deliveries with endpoint, status, event, run and time filters, POST /webhook-deliveries/{id}/retry and the catalogue GET /webhook-events (WebhookEventType, WEBHOOK_EVENTS, webhookEventOf, WebhookPayload, WebhookEndpoint, WebhookEndpointInput, CreatedWebhookEndpoint, RotatedWebhookSecret, WebhookTestResult, WebhookDelivery, WebhookDeliveryStatus, WebhookDeliveryFilter, WEBHOOK_MAX_ATTEMPTS, WEBHOOK_RETRY_DELAYS_MS, WEBHOOK_SECRET_OVERLAP_MS). Notifications: GET /notifications and POST /notifications/read (Notification, NotificationKind, NotificationList, NotificationQuery, MarkNotificationsRead, NotificationsMarked). RunRelated gains deliveries; AttentionItem gains webhook_exhausted. New environment variable WEBHOOK_ALLOW_PRIVATE_NETWORKS. The client adds webhooks and notifications.

• 0019b2e: New permissions for the console routes to come: runs:write, ops:read, webhooks:read, webhooks:write and users:manage (admins) and notifications:read (admins and analysts). Named errors queue_name_taken (QueueNameTakenError), case_not_assigned (CaseNotAssignedError: deciding someone else's case; an unassigned case is claimed by the decision) and rate_limited (429 with Retry-After, per caller, API_RATE_LIMIT_PER_MINUTE). The client adds isQueueNameTaken, isCaseNotAssigned and isRateLimited.

• ff4da19: Plugins: a manifest may give category, vendor, docsUrl (https) and pricingNote, which GET /plugins/available returns with actionDetails, each action's timeout, retry policy, idempotency, webhook timeout and input and output JSON Schemas (PluginSummary, PluginActionSummary). GET /plugins/health adds circuits, the plugins whose circuit breaker the workers report open or half-open (PluginCircuit, PluginCircuitState); Home's plugin_failing attention item carries circuit. POST /plugins/{name}/test calls one synchronous action once with the tenant configuration (TestPluginInput, PluginTestResult). POST /plugins/{name}/secrets/{secret} stores a secret value sealed with SECRET_STORE_KEY and answers its store: reference (SetPluginSecretInput, PluginSecretRef); DELETE revokes it. Service users: GET, POST /service-users, PATCH /service-users/{id}, POST /service-users/{id}/keys (the token is returned once) and DELETE /service-users/{id}/keys/{keyId} manage the tenant's machine users in Zitadel with ZITADEL_MANAGEMENT_PAT (ServiceUser, ServiceUserKey, CreateServiceUserInput, UpdateServiceUserInput, CreateServiceUserKeyInput, IssuedServiceUserKey). New errors: secret_store_unavailable and service_users_unavailable (503). The client adds plugins.test, plugins.setSecret, plugins.revokeSecret and serviceUsers; its PluginSummary is core's.

• f1b6377: Runs record what started them (trigger: api, console or replay) and the caller's correlationId, set on POST /workflow-runs, filtered with trigger and matched exactly by search. The worker traces every step visit: GET /workflow-runs/{id}/steps returns each visit's status, timings, summary, input and output and the rows it wrote (RunStep), and GET /workflow-runs/{id}/related the run's cases, decision, replay links and, for ops:read, a trace link (RunRelated, TRACE_URL_TEMPLATE). Admins cancel an active run (POST /workflow-runs/{id}/cancel, which closes its open cases and withdraws its forms) and replay a finished one from a step it reached (POST /workflow-runs/{id}/replay). New errors run_finished, run_active and step_not_reached (RunFinishedError, RunActiveError, StepNotReachedError); the client adds workflowRuns.steps, related, cancel and replay and isRunFinished, isRunActive and isStepNotReached.

• dec5e57: Search, Home, health and document thumbnails. GET /search finds subjects, cases, runs and definitions as far as the caller may read (SearchQuery, SearchResults, SearchGroup, SearchItem, SearchItemKind, SearchScope). GET /setup/checklist computes the setup steps (SetupChecklist, SetupItem, SetupItemId) and GET /activity tells recent decisions, breaches, publishes and approvals as sentences (ActivityFeed, ActivityItem, ActivityQuery). GET /health/summary reports the dependencies, failing plugins and given-up webhooks (HealthSummary, HealthState, DependencyStatus). The scan renders a grayscale thumbnail of clean images and of a PDF's first page (Document.thumbnailKey), served by GET /documents/{id}/thumbnail (DocumentThumbnail). The client adds home.search, home.setupChecklist, home.activity, health.summary and documents.thumbnail.

• bcce30e: Statistics: GET /stats/overview answers Home's figures (StatsOverview: open, unassigned, breached and due cases, the last 24 hours of runs with autoDecidedPct, and the AttentionItems the caller may act on); GET /stats/definitions?kind= the activity per rule, workflow or collection flow over 1 to 90 days (DefinitionStats: RuleStats, WorkflowStats, FlowStats); GET /stats/sla SLA attainment, breaches and median time to decide, per workflow (SlaStats); GET /stats/rules/{key}/hits a rule's recorded hits per UTC day and, with compareVersion, that version's backtest beside them (RuleHits). A rule backtest's summary adds daily (BacktestDay). GET /cases, /subjects, /audit-events, /workflow-runs and /plugin-invocations stop counting at 100,000 and flag it with totalIsEstimate. GET /workflow-runs/summary takes every filter of the list and adds autoDecidedPct. GET /decisions pages (limit, offset, from, to) and returns total. GET /subjects/{id}/timeline pages by cursor and answers TimelinePage ({ items, nextCursor }) in place of offset. GET /plugin-callbacks filters by pluginName and returns total. The client adds stats (overview, definitions, sla, ruleHits), pluginCallbacks.list, decisions.listPage and Page.totalIsEstimate; subjects.timeline returns the page with its cursor, and workflowRuns.summary takes the list's filters. Core adds percentOf.

• 774356c: Subjects can be changed with PATCH /subjects/{id} (UpdateSubjectInput: data as a JSON merge patch, tags, status), audited as subject.updated with the changed paths; core adds applyMergePatch, diffMergePatch and changedPaths. GET /subjects/{id} returns lastSeenAt (SubjectDetail), GET /subjects/{id}/links the subjects sharing a device, card, IP address, email, address or referral (SubjectLink), and GET /subjects/{id}/flags the derived signals (SubjectFlag). GET /subjects filters on country and lastDecision, and GET /subjects/export returns the filtered list as CSV. The client adds subjects.update, links, flags and exportCsv.

• 98d2fec: Tenant settings gain cases.warnAtPct (the share of the SLA left when a new case turns due_soon, kept on the case as slaWarnPct), collection.defaultLinkTtlSeconds (the lifetime of links for flows that set none; CollectionFlowBody.linkTtlSeconds is optional and linkLifetime resolves it), and console.showRunContextTo and console.maskForAnalysts, which decide what people see of run context and personal data (maskPersonalData takes the kinds to mask; PERSONAL_DATA_KINDS). TenantProfile.region reports DEPLOYMENT_REGION. Statistics count days in the tenant's console.timeZone (RuleHits.timeZone; dayIn, midnightIn, daysIn).

• f4cfd62: Tenant settings gain namespaces: cases.businessHours (BusinessHours, used by addBusinessTime to compute due times) and cases.onBreach (BreachActions), approvals.requiredFor (checked by approvalRequired), collection.flowUrl (CollectionSettings) and console (ConsoleSettings); tenant.settings.updated records the changed paths. Tenant gains status, suspendedAt, suspendedReason and linksValidAfter. New routes: GET /tenants/me (TenantProfile), POST /tenants/me/suspend (SuspendTenantInput), POST /tenants/me/resume and POST /tenants/me/revoke-links (RevokedLinks), each behind a recent sign-in sent as X-Aletheia-Reauth; GET /roles (RoleDescription); GET and PUT /me/preferences (UserPreferences); and the team under /team (TeamUser, InviteUserInput, ChangeRoleInput). Errors TenantSuspendedError (tenant_suspended) and ReauthRequiredError (reauth_required) are new. The client adds tenants.profile, suspend, resume, revokeLinks, roles, preferences, updatePreferences and tenants.team, the isTenantSuspended and isReauthRequired guards, and per-request headers.

0.4.0

Minor Changes

• 3282c50: GET /collection-submissions lists submissions newest first, filtered by subjectId, workflowRunId and status, with the total. CollectionSubmissionFilter describes the filters, and the client's collectionSubmissions.list and listPage call it.

0.3.0

Minor Changes

• ffa9107: API_CORS_ORIGINS now defaults to empty. The admin console and the collection terminal call the API through their own origin, so a deployment lists only the other browser origins that call the API directly.

• eb2c640: Schemas for the case and subject list additions: CaseListItem and CaseExpand (GET /cases?expand=subject), SubjectSummary, SubjectListItem, SubjectExpand and SubjectLastDecision (GET /subjects?expand=openCases&expand=lastDecision), CaseCountsInput and CaseCounts with MAX_CASE_COUNT_FILTERS, ClaimNextCaseInput, and BulkCaseInput, BulkCaseAction and BulkCaseResult with MAX_BULK_CASES. New helpers subjectDisplayName, subjectCountry and toSubjectSummary derive a subject's display name and country from its free-form data.

• 7c5c045: Two optional collection-flow Field properties for applicant-facing copy: unit, a short unit (1 to 12 characters, such as % or GBP) shown after a number input, and messages (FieldMessages), author-written required and invalid error copy (1 to 200 characters each, trimmed) that replaces the generated messages. Both are display only: answers are validated exactly as before, and flows without them parse unchanged.

• eb2c640: New masking module: maskEmail, maskPhone, maskDocumentNumber, maskDateOfBirth, personalDataKind (the key classifier), maskAttribute, maskPersonalData (deep, by key), redactValues (every leaf becomes [redacted], exported as REDACTED) and isHiddenValue. The API uses them to mask personal data for callers without subjects:pii and to redact run context and plugin payloads for callers without runs:context.

• eb2c640: Schemas for the tenant-wide run list and the plugin figures: WorkflowRunFilter, WorkflowRunExpand and WorkflowRunListItem (a run with durationMs, the outcome of its decision and, with expand=subject, its SubjectSummary) for GET /workflow-runs; WorkflowRunSummaryQuery and WorkflowRunSummary (total, byStatus with every status, p95DurationMs) for GET /workflow-runs/summary; PluginInvocationFilter for GET /plugin-invocations; and PluginHealthQuery, PluginHealth, PluginHealthReport and PLUGIN_HEALTH_WINDOW_MINUTES for GET /plugins/health.

0.2.0

Minor Changes

• 1b1c13f: New PolicyPack schema and helpers (policy-pack.ts): a portable set of rules, rule sets, workflows, collection flows and lists (with rows, capped at POLICY_PACK_MAX_LIST_ROWS) built from the same input schemas the PUT routes accept, plus PolicyPackKeyRef (<kind>:<key>), parsePolicyPackKeyRef, policyPackKeyRefs and policyPackCounts. It is the body of POST /definitions/import and the response of GET /definitions/export.

0.1.0

Minor Changes

• a783a44: First published release. @aletheia-dev/api-client and @aletheia-dev/collection-flow-ui are published for teams that embed collection flows or build their own back office; @aletheia-dev/core and @aletheia-dev/collection-flow are published as their dependencies and carry no stability promise before 1.0.