bkper 5.0.0 → 5.2.0

package/lib/docs/apps/ai.md

@@ -1,123 +1,155 @@
 # Add Bkper AI to an App
 
-Bkper Platform apps can call [Bkper AI](https://bkper.com/docs/ai/ai-gateway.md) without storing a model-provider key. The platform authorizes the Worker's request using the current user and attributes usage to the app. Model output is a suggestion, not permission to change a Book: keep decisions about resource movements and any resulting writes in application code.
+Bkper Platform apps can call [Bkper AI](https://bkper.com/docs/ai/ai-gateway.md) without storing a model-provider key. The platform authorizes each request as the current user and attributes usage to the app. Scripts and servers outside the platform use the same code with their own Bkper token.
 
-This guide covers a server-side, non-streaming language response. It uses AI SDK to draft a review note from a transaction description. No Book data is written by the example.
+Model output is a suggestion, not permission to change a Book. Keep decisions about resource movements, and any resulting writes, in application code.
 
 ## Choose the kind of response
 
-- **A bounded yes/no, choice, or score?** Use a typed evaluation at `POST /v1/evaluations`.
-- **Generated text or a custom JSON object?** Use a language model at `POST /v1/responses`. AI SDK is an option for this path.
+- **A yes/no, a choice, or a level on a scale?** Ask a decision model, such as `jev`, with TypeSafe's SDK, `@typesafe-ai/sdk`.
+- **Text or a custom JSON object?** Ask a language model (LLM), such as `gpt-luna`, with AI SDK's Open Responses provider, `@ai-sdk/open-responses`.
 
-Pick a model of the corresponding `type` from the live [`GET /v1/models` catalog](https://ai.bkper.app/v1/models). The catalog also tells you which language models support strict structured output. AI SDK's **Open Responses provider** covers language responses, not Bkper's typed evaluation endpoint. For evaluation models, use HTTP or implement an AI SDK evaluation-model adapter for `experimental_evaluate`, as `bkper-agent` does. See the [Typed Evaluations guide](https://bkper.com/docs/ai/evaluations.md) for requests, responses, decision thresholds, and errors, and the [Merge Duplicates app](https://github.com/bkper/bkper-apps/tree/main/merge-duplicates) for a human-reviewed HTTP example.
+Add the SDK to the **Worker** package. Keep the call in a server service used by your authenticated app API route, and define the route's request and response in the app's Zod/OpenAPI contract.
 
 ## Keep authentication in the platform
 
 For an interactive app, the flow is:
 
-1. The client calls a typed app `/api/*` route through `auth.authenticatedFetch()` (or another authenticated client). The template's generated API client can use that fetch provider.
+1. The client calls a typed app `/api/*` route through `auth.authenticatedFetch()` or another authenticated client.
 2. Bkper verifies the user's token, removes it before invoking the Worker, and establishes user and app context for outbound requests.
-3. The Worker calls `https://ai.bkper.app/v1/*`. Platform outbound adds authorization and app attribution. **Do not read, forward, or store the user's token in the Worker.**
+3. The Worker calls Bkper AI. Platform outbound adds authorization and app attribution. **Do not read, forward, or store the user's token in the Worker.**
 
-An authenticated `/events` handler has the same outbound context. A page request does not; start interactive inference from an authenticated `/api/*` route, not from the page handler or the browser.
+An authenticated `/events` handler has the same outbound context. A page request does not; start inference from an authenticated `/api/*` route, not from the page handler or the browser.
 
-## Example: draft a review note with AI SDK
+## Ask a decision model
 
-Add `ai`, `@ai-sdk/open-responses`, and `zod` to the **Worker** package. Keep this code in a server service called from your authenticated app API route; define the route's request and response in the app's Zod/OpenAPI contract. The service takes only the description needed for this task, discovers the current language model, and validates its output before returning it to the caller.
+```ts
+import { score, TypeSafeClient } from '@typesafe-ai/sdk';
+
+const decisionClient = new TypeSafeClient({
+    apiKey: 'bkper-platform-outbound',
+    baseURL: 'https://ai.bkper.app',
+    defaultModel: 'jev',
+});
+
+export async function scoreRecurring(description: string) {
+    const { answers } = await decisionClient.systemOne({
+        state: { description },
+        questions: {
+            recurring: score('How likely is this a recurring charge?', [
+                'Unlikely',
+                'Possible',
+                'Likely',
+            ]),
+        },
+    });
+    return answers.recurring;
+}
+```
+
+- **`apiKey`** is required by the SDK. In a Platform Worker, pass any placeholder: platform outbound replaces it with the user's authorization.
+- **`baseURL`** has no `/v1`. The SDK calls `POST /v1/systemone`, which behaves exactly like `POST /v1/decisions`.
+- **The answer is typed** from the question. Bkper AI validates every answer against its question before responding, so your code can use it directly.
+
+The Decision Models guide covers questions, state, answers, and thresholds. The open-source [Merge Duplicates app](https://github.com/bkper/bkper-apps/tree/main/merge-duplicates) uses this setup to suggest duplicate pairs for human review.
+
+## Generate a language response
 
 ```ts
 import { createOpenResponses } from '@ai-sdk/open-responses';
 import { generateText, Output } from 'ai';
 import { z } from 'zod';
 
-const BASE_URL = 'https://ai.bkper.app/v1';
-const ReviewNote = z.strictObject({ note: z.string() });
-
-export async function draftReviewNote(
-    description: string,
-    fetcher: typeof fetch = fetch
-): Promise<{ note: string }> {
-    const response = await fetcher(`${BASE_URL}/models`);
-    if (!response.ok) throw new Error(`Model discovery failed (${response.status}).`);
-
-    const catalog = z
-        .object({
-            default_model: z.string(),
-            data: z.array(
-                z.object({
-                    id: z.string(),
-                    type: z.string(),
-                    structured_output: z
-                        .object({
-                            json_schema: z.boolean(),
-                            strict: z.boolean(),
-                        })
-                        .optional(),
-                })
-            ),
-        })
-        .parse(await response.json());
-    const model = catalog.data.find(item => item.id === catalog.default_model);
-    if (
-        model?.type !== 'language' ||
-        !model.structured_output?.json_schema ||
-        !model.structured_output.strict
-    ) {
-        throw new Error('The default model does not support strict JSON output.');
-    }
-
-    const provider = createOpenResponses({
-        name: 'bkper-ai',
-        url: `${BASE_URL}/responses`,
-        fetch: fetcher,
-    });
+const llmClient = createOpenResponses({
+    name: 'bkper-ai',
+    url: 'https://ai.bkper.app/v1/responses',
+});
+
+export async function draftReviewNote(description: string) {
     const { output } = await generateText({
-        model: provider(model.id),
-        system: 'Draft a short, neutral review note. Do not invent facts or change Accounts.',
+        model: llmClient('gpt-luna'),
+        system: 'Draft a short, neutral review note. Do not invent facts.',
         prompt: description,
-        output: Output.object({ schema: ReviewNote }),
-        maxRetries: 0,
+        output: Output.object({ schema: z.object({ note: z.string() }) }),
     });
-    return ReviewNote.parse(output);
+    return output;
 }
 ```
 
-**This example is for a Bkper Platform Worker.** With no SDK `apiKey`, the Open Responses provider sends no `Authorization` header; platform outbound supplies authorization and app attribution. A standalone integration such as `bkper-agent` must instead obtain and send its own Bkper OAuth token. Open Responses always requests `strict: true` for structured JSON and omits `store`; Bkper AI treats an omitted `store` as `false` and never persists response state. If you need `strict: false` for a model-supported flexible schema, use `@ai-sdk/openai` with its `.responses()` model and `strictJsonSchema: false`, as `bkper-agent` does. You may cache the catalog briefly instead of fetching it for every call.
+- **No `apiKey`.** The provider then sends no `Authorization` header, and platform outbound adds it.
+- **`url`** is the full `/v1/responses` URL.
+- **`output`** is parsed and validated against your schema by AI SDK. The provider requests strict structured output, which every Bkper language model supports.
 
-The schema deliberately checks only that a `note` string exists. Constraints such as a minimum or maximum string length are **not needed for this example** and may not be supported by every model's strict JSON Schema subset. If your app needs a length limit, check it in application code after generation.
-
-## Before using the result
+Keep schemas simple. Constraints such as a string's minimum or maximum length may not be supported by every model's strict JSON Schema subset; check them in code after generation.
 
-- Send only task-relevant data. Validate input and Book permissions at the app API boundary. A generated note must not create, merge, or alter a transaction without deterministic application rules and any required human confirmation.
-- If model discovery fails or output does not match the schema, fail safely. Avoid automatic retries on actions that may consume allowance.
-- When the AI request fails, preserve the upstream HTTP status, error code, and message **when Bkper AI supplies them**, so users can understand failures such as an exhausted allowance. AI SDK exposes HTTP failures as `APICallError`; read the Bkper AI error envelope from `responseBody`, not from the SDK's generic message. For `NoObjectGeneratedError` or transport errors, return a safe app-defined error instead. Do not return prompts, raw responses, or stack traces to clients.
-- Unit-test the server service with a mocked `fetch`: verify the model's type and capability, that no `Authorization` or attribution headers leave the Worker, that only necessary data is sent and `store: true` is never requested, that malformed output is rejected, and that errors remain actionable. Then run the app's normal check/build.
+## Outside a Platform app
 
-For example, a route can extract the safe fields before mapping them into its typed error response:
+Scripts, servers, and tools send their own Bkper token. Pass it as `apiKey`: both SDKs send it as a bearer token. Get a client each time you need one, so every call uses a current token:
 
 ```ts
-import { APICallError } from 'ai';
-
-function bkperAiError(error: unknown) {
-    if (!APICallError.isInstance(error)) return null;
-    let body: unknown;
-    try {
-        body = JSON.parse(error.responseBody ?? '');
-    } catch {
-        return null;
-    }
-    const parsed = z
-        .object({
-            error: z.object({ code: z.string(), message: z.string() }),
-        })
-        .safeParse(body);
-    if (!parsed.success) return null;
-    return {
-        status: error.statusCode ?? 502,
-        code: parsed.data.error.code,
-        message: parsed.data.error.message,
-    };
-}
+import { createOpenResponses } from '@ai-sdk/open-responses';
+import { noul, TypeSafeClient } from '@typesafe-ai/sdk';
+import { generateText } from 'ai';
+import { getOAuthToken } from 'bkper';
+
+const decisionClient = async () =>
+    new TypeSafeClient({
+        apiKey: await getOAuthToken(),
+        baseURL: 'https://ai.bkper.app',
+        defaultModel: 'jev',
+    });
+
+const llmClient = async () =>
+    createOpenResponses({
+        name: 'bkper-ai',
+        url: 'https://ai.bkper.app/v1/responses',
+        apiKey: await getOAuthToken(),
+    });
+
+const client = await decisionClient();
+const { answers } = await client.systemOne({
+    state: { description: 'NETFLIX.COM monthly plan' },
+    questions: { streaming: noul('Is this a streaming service?') },
+});
+
+const { text } = await generateText({
+    model: (await llmClient())('gpt-luna'),
+    prompt: 'Describe NETFLIX.COM monthly plan in five words.',
+});
 ```
 
-For direct HTTP calls, advanced features, or exact request and response fields, use the [Bkper AI API reference](https://bkper.com/docs/api/ai.md) and [AI Gateway guide](https://bkper.com/docs/ai/ai-gateway.md). Bkper AI implements a documented subset of Open Responses, not every OpenAI or AI SDK feature.
+- **`getOAuthToken()`** reads the credentials from `bkper auth login` and refreshes them when needed. In your own server, use your own token provider.
+- **Creating a client is cheap.** Neither SDK makes a request until you ask a question.
+- **Label your usage** with a `bkper-ai-source` header, such as `my-script`: `defaultHeaders` in the TypeSafe SDK, `headers` in Open Responses. In a Platform app, outbound sets the source to the app.
+
+## Handle errors
+
+Every Bkper AI error has the same envelope: `{ error: { message, type, param, code } }`. Branch on `error.code`, not only on the HTTP status: a `429` can mean an exhausted allowance or a throttled provider.
+
+- **TypeSafe SDK:** an `APIError` with `status` and the envelope in `body`, so read `error.body.error.code`. Network failures and timeouts throw `APIConnectionError`.
+- **AI SDK:** an `APICallError` with `statusCode` and the envelope in `data`, so read `error.data.error.code`. Output that does not match your schema throws `NoObjectGeneratedError`.
+
+Both SDKs retry rate limits and server errors twice by default. A failed attempt costs nothing: Bkper AI charges only successful answers.
+
+Map these errors to your route's typed error response. Keep the code and message so users understand failures such as an exhausted allowance, but never return prompts, raw responses, or stack traces.
+
+## SDK notes
+
+- **Passing your own `fetch`.** The TypeSafe SDK calls `fetch` as its own method, which the Workers runtime rejects with `Illegal invocation`. Wrap it: `fetch: (input, init) => myFetch(input, init)`. Without the option, the SDK's default works.
+- **No `null` values.** The TypeSafe SDK's types accept `null` for state, instructions, and some criteria. Bkper AI rejects them with `400`.
+- **No `client.models.list()`.** It expects TypeSafe's catalog shape. Use the [`GET /v1/models`](https://ai.bkper.app/v1/models) catalog.
+- **Other System One clients** take `https://ai.bkper.app/v1` as their base URL.
+- **Flexible JSON schemas.** Open Responses always requests `strict: true`. For a schema that needs `strict: false`, such as a typed dynamic map, use `@ai-sdk/openai` with base URL `https://ai.bkper.app/v1`, its `.responses()` model, and `strictJsonSchema: false`.
+
+## Before using the result
+
+- **Send only task-relevant data.** Validate input and Book permissions at the app API boundary.
+- **Keep writes deterministic.** An answer or generated text must not create, merge, or alter a Transaction without application rules and any required human confirmation.
+- **Test the service.** Mock `fetch` and check what is sent, that the Worker adds no user token, and that errors stay actionable. Then run the app's normal check and build.
+
+## Next steps
+
+- [Decision Models](https://bkper.com/docs/ai/decision-models.md): questions, answers, thresholds, and caching.
+- [Bkper AI Gateway](https://bkper.com/docs/ai/ai-gateway.md): tokens, raw HTTP requests, errors, and privacy.
+- [Models and Usage](https://bkper.com/docs/ai/models.md): model IDs, capabilities, and usage rates.
+- [Bkper AI API reference](https://bkper.com/docs/api/ai.md): every request and response field.

package/lib/docs/apps/event-handlers.md

@@ -244,5 +244,17 @@ The complete API set of event types is listed below. `COMMENT_CREATED` and `COMM
 | `INTEGRATION_DELETED` | An integration was deleted. |
 | `BOOK_CREATED` | A book was created. |
 | `BOOK_AUDITED` | A balances audit completed for the book. |
+| `BOOK_OVERNIGHT` | Daily scheduled event for the book, delivered at or after 01:00 in the book's time zone. |
 | `BOOK_UPDATED` | Book settings were updated. |
 | `BOOK_DELETED` | The book was deleted. |
+
+### Scheduled work with `BOOK_OVERNIGHT`
+
+`BOOK_OVERNIGHT` lets your app run daily work on a book without waiting for a user action — for example, end-of-day recalculations, fetching external data, or consistency checks.
+
+- **When:** once per day, at or after 01:00 in the book's time zone (UTC if the book has no time zone). Delivery may be up to about an hour later.
+- **Which books:** only books where an installed app subscribes to `BOOK_OVERNIGHT`. Books without such an app receive nothing.
+- **What day:** each event represents the local day that just ended. A book gets at most one `BOOK_OVERNIGHT` event per local day.
+- **Idempotency:** the event `id` is stable for the book and day, so use it to skip repeated deliveries.
+- **User:** the event `user` is the book owner. Your handler still runs on behalf of the user who installed the app.
+- **Development webhook:** `webhookUrlDev` is used when the user who installed the app is its owner or one of its developers.

package/lib/docs/apps/overview.md

@@ -20,7 +20,7 @@ The same Worker can expose app-defined `/api/*` routes. Treat those routes as th
 
 When an app needs model inference, use Bkper AI by default. An authenticated app API route or event establishes the user and app identity, then platform outbound supplies authorization and usage attribution for the Worker's Bkper AI requests. The app does not need provider credentials.
 
-See [Add Bkper AI to an App](https://bkper.com/docs/platform/apps/ai.md) for live model discovery, strict structured output, validation, and the client-to-Worker authentication flow.
+See [Add Bkper AI to an App](https://bkper.com/docs/platform/apps/ai.md) for the client-to-Worker authentication flow and SDK setup for decision and language models.
 
 ### Authentication
 

package/lib/docs/cli/app-management.md

@@ -459,6 +459,7 @@ events:
     - BOOK_UPDATED
     - BOOK_DELETED
     - BOOK_AUDITED
+    - BOOK_OVERNIGHT # Daily per-Book event, at or after 01:00 in the Book's time zone
 
 # -----------------------------------------------------------------------------
 # FILE PATTERNS (optional)

package/lib/docs/index.md

@@ -10,7 +10,8 @@ For Bkper app implementation, refactoring, or code review, always read `apps/qua
 - `cli/data-management.md` — CLI reference for managing financial data and files: books, accounts, groups, files, transactions, per-account balance queries, query operators (on:, after:, before:, account:, group:), JSON output shapes and jq reshaping, human-review Bkper UI links, batch operations via stdin/piping, collections.
 - `cli/app-management.md` — CLI reference for building and deploying Bkper apps: init/git clone/credential helpers, dev/build/deploy workflow, app install/uninstall, secrets management, app logs, bkper.yaml configuration reference (identity, branding, events, menu integration, deployment).
 - `apps/overview.md` — Platform evaluation and capability overview: use when comparing managed Bkper hosting with self-managed infrastructure or clarifying platform responsibilities; use the task-specific app references for implementation.
-- `apps/ai.md` — Bkper AI in Platform apps: choose Jev typed evaluations or Open Responses language models, authenticate through app `/api/*` routes, discover model capabilities, validate output, and keep Book writes under deterministic application control.
+- `apps/ai.md` — Bkper AI in apps, scripts, and tools: ask the Jev decision model with TypeSafe's SDK or language models with AI SDK Open Responses, authenticate through app `/api/*` routes or a Bkper token outside the platform, handle errors, and keep Book writes under deterministic application control.
+- `ai/decision-models.md` — Automating recurring judgments in code, such as categorizing bank lines, matching duplicates, or flagging entries, with Bkper AI decision models: writing questions and state, reading calibrated answers, and acting only above thresholds while routing uncertain cases to a person.
 - `apps/first-app.md` — First-app walkthrough: scaffold, install, run locally, trigger an event, customize the listing, establish shared source, check, and deploy.
 - `apps/architecture.md` — App and template architecture: npm workspace structure, Lit/Vite client, Hono Worker, typed `/api/*` contracts, authentication, `/events`, static assets, and supported app shapes.
 - `apps/quality.md` — Cross-cutting quality guidance for Bkper apps: UI consistency, immediate first rendering, typed API contracts, cohesive low-coupling modules, separation of business behavior from connectors and storage, security, and final implementation review. Load for app implementation, refactoring, or review tasks.

package/lib/docs/sdk/bkper-api-types.md

@@ -89,7 +89,7 @@ More information at the [Bkper Developer Documentation](https://bkper.com/docs/#
 - `deprecated?`: `boolean` — Whether the app is deprecated
 - `description?`: `string` — The App description
 - `developers?`: `string` — The developers (usernames and domain patterns), comma or space separated
-- `events?`: `("FILE_CREATED" | "FILE_UPDATED" | "FILE_DELETED" | "TRANSACTION_CREATED" | "TRANSACTION_UPDATED" | "TRANSACTION_DELETED" | "TRANSACTION_POSTED" | "TRANSACTION_CHECKED" | "TRANSACTION_UNCHECKED" | "TRANSACTION_RESTORED" | "ACCOUNT_CREATED" | "ACCOUNT_UPDATED" | "ACCOUNT_DELETED" | "QUERY_CREATED" | "QUERY_UPDATED" | "QUERY_DELETED" | "GROUP_CREATED" | "GROUP_UPDATED" | "GROUP_DELETED" | "COMMENT_CREATED" | "COMMENT_DELETED" | "COLLABORATOR_ADDED" | "COLLABORATOR_UPDATED" | "COLLABORATOR_REMOVED" | "INTEGRATION_CREATED" | "INTEGRATION_UPDATED" | "INTEGRATION_DELETED" | "BOOK_CREATED" | "BOOK_AUDITED" | "BOOK_UPDATED" | "BOOK_DELETED")[]` — Event types the App listen to
+- `events?`: `("FILE_CREATED" | "FILE_UPDATED" | "FILE_DELETED" | "TRANSACTION_CREATED" | "TRANSACTION_UPDATED" | "TRANSACTION_DELETED" | "TRANSACTION_POSTED" | "TRANSACTION_CHECKED" | "TRANSACTION_UNCHECKED" | "TRANSACTION_RESTORED" | "ACCOUNT_CREATED" | "ACCOUNT_UPDATED" | "ACCOUNT_DELETED" | "QUERY_CREATED" | "QUERY_UPDATED" | "QUERY_DELETED" | "GROUP_CREATED" | "GROUP_UPDATED" | "GROUP_DELETED" | "COMMENT_CREATED" | "COMMENT_DELETED" | "COLLABORATOR_ADDED" | "COLLABORATOR_UPDATED" | "COLLABORATOR_REMOVED" | "INTEGRATION_CREATED" | "INTEGRATION_UPDATED" | "INTEGRATION_DELETED" | "BOOK_CREATED" | "BOOK_AUDITED" | "BOOK_OVERNIGHT" | "BOOK_UPDATED" | "BOOK_DELETED")[]` — Event types the App listen to
 - `filePatterns?`: `string[]` — File patterns the App handles - wildcard accepted. E.g. *.pdf, *-bank.csv
 - `id?`: `string` — The unique agent id of the App - this can't be changed after created
 - `installable?`: `boolean` — Whether this app is installable in a book
@@ -331,7 +331,7 @@ More information at the [Bkper Developer Documentation](https://bkper.com/docs/#
 - `data?`: `bkper.EventData`
 - `id?`: `string` — The unique id that identifies the Event
 - `resource?`: `string` — The resource associated to the Event
-- `type?`: `"FILE_CREATED" | "FILE_UPDATED" | "FILE_DELETED" | "TRANSACTION_CREATED" | "TRANSACTION_UPDATED" | "TRANSACTION_DELETED" | "TRANSACTION_POSTED" | "TRANSACTION_CHECKED" | "TRANSACTION_UNCHECKED" | "TRANSACTION_RESTORED" | "ACCOUNT_CREATED" | "ACCOUNT_UPDATED" | "ACCOUNT_DELETED" | "QUERY_CREATED" | "QUERY_UPDATED" | "QUERY_DELETED" | "GROUP_CREATED" | "GROUP_UPDATED" | "GROUP_DELETED" | "COMMENT_CREATED" | "COMMENT_DELETED" | "COLLABORATOR_ADDED" | "COLLABORATOR_UPDATED" | "COLLABORATOR_REMOVED" | "INTEGRATION_CREATED" | "INTEGRATION_UPDATED" | "INTEGRATION_DELETED" | "BOOK_CREATED" | "BOOK_AUDITED" | "BOOK_UPDATED" | "BOOK_DELETED"` — The type of the Event
+- `type?`: `"FILE_CREATED" | "FILE_UPDATED" | "FILE_DELETED" | "TRANSACTION_CREATED" | "TRANSACTION_UPDATED" | "TRANSACTION_DELETED" | "TRANSACTION_POSTED" | "TRANSACTION_CHECKED" | "TRANSACTION_UNCHECKED" | "TRANSACTION_RESTORED" | "ACCOUNT_CREATED" | "ACCOUNT_UPDATED" | "ACCOUNT_DELETED" | "QUERY_CREATED" | "QUERY_UPDATED" | "QUERY_DELETED" | "GROUP_CREATED" | "GROUP_UPDATED" | "GROUP_DELETED" | "COMMENT_CREATED" | "COMMENT_DELETED" | "COLLABORATOR_ADDED" | "COLLABORATOR_UPDATED" | "COLLABORATOR_REMOVED" | "INTEGRATION_CREATED" | "INTEGRATION_UPDATED" | "INTEGRATION_DELETED" | "BOOK_CREATED" | "BOOK_AUDITED" | "BOOK_OVERNIGHT" | "BOOK_UPDATED" | "BOOK_DELETED"` — The type of the Event
 - `user?`: `bkper.User`
 
 ### EventData
@@ -547,6 +547,8 @@ More information at the [Bkper Developer Documentation](https://bkper.com/docs/#
 - `id?`: `string` — The user unique id
 - `name?`: `string` — The user display name
 - `plan?`: `string` — The user plan
+- `planAmount?`: `number` — The confirmed recurring plan total in currency minor units
+- `planCurrency?`: `string` — The confirmed recurring plan currency
 - `planCycle?`: `"MONTHLY" | "YEARLY"` — The user plan billing cycle
 - `planOverdue?`: `boolean` — True if subscription payment is overdue
 - `startedTrial?`: `boolean` — True if user started trial

package/lib/docs/sdk/bkper-js.md

@@ -1403,6 +1403,7 @@ Enum that represents event types.
 - `BOOK_AUDITED`
 - `BOOK_CREATED`
 - `BOOK_DELETED`
+- `BOOK_OVERNIGHT` — Daily per-Book event for Apps subscribed to it, delivered at or after 01:00 in the Book's time zone.
 - `BOOK_UPDATED`
 - `COLLABORATOR_ADDED`
 - `COLLABORATOR_REMOVED`

package/lib/upgrade/index.d.ts

@@ -1,5 +1,6 @@
-export { VERSION, detectMethod, detectMethodAsync, fetchLatestVersion, getUpgradeCommand, isVersionInstalledAsync, startDetachedUpgrade, } from './installation.js';
-export { autoUpgrade, foregroundUpgrade, getAvailableUpgrade, isNewerVersion, } from './upgrade.js';
-export type { InstallMethod } from './installation.js';
-export type { AvailableUpgrade } from './upgrade.js';
+export { PACKAGE_DIR, VERSION, detectInstallMethod, fetchLatestVersion, getInstallCommand, getSelfUpdatePlan, } from './installation.js';
+export { foregroundUpgrade, isNewerVersion, runUpgrade } from './upgrade.js';
+export { formatUpdateNotice, getUpdateNotice, isUpdateCheckDisabled, maybeStartUpdateCheck, readUpdateState, runCommandUpdateCheck, } from './update-check.js';
+export type { InstallMethod, SelfUpdatePlan } from './installation.js';
+export type { UpdateNotice } from './update-check.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/upgrade/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/upgrade/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,OAAO,EACP,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACH,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,GACjB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/upgrade/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,WAAW,EACX,OAAO,EACP,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,EACH,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,qBAAqB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACvE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/lib/upgrade/index.js

@@ -1,3 +1,4 @@
-export { VERSION, detectMethod, detectMethodAsync, fetchLatestVersion, getUpgradeCommand, isVersionInstalledAsync, startDetachedUpgrade, } from './installation.js';
-export { autoUpgrade, foregroundUpgrade, getAvailableUpgrade, isNewerVersion, } from './upgrade.js';
+export { PACKAGE_DIR, VERSION, detectInstallMethod, fetchLatestVersion, getInstallCommand, getSelfUpdatePlan, } from './installation.js';
+export { foregroundUpgrade, isNewerVersion, runUpgrade } from './upgrade.js';
+export { formatUpdateNotice, getUpdateNotice, isUpdateCheckDisabled, maybeStartUpdateCheck, readUpdateState, runCommandUpdateCheck, } from './update-check.js';
 //# sourceMappingURL=index.js.map

package/lib/upgrade/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/upgrade/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,OAAO,EACP,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACH,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,GACjB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/upgrade/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,WAAW,EACX,OAAO,EACP,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,EACH,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,qBAAqB,GACxB,MAAM,mBAAmB,CAAC"}

package/lib/upgrade/installation.d.ts

@@ -1,38 +1,72 @@
 /** Current installed version of the CLI. */
 export declare const VERSION: string;
+/** Directory of the running bkper package (the folder holding its package.json). */
+export declare const PACKAGE_DIR: string;
 /** Supported installation methods. */
-export type InstallMethod = 'npm' | 'bun' | 'yarn' | 'unknown';
-export type CommandRunner = (command: string, timeoutMs: number) => Promise<string>;
-export type DetachedCommandStarter = (command: string) => void;
+export type InstallMethod = 'npm' | 'pnpm' | 'yarn' | 'bun' | 'unknown';
+/** Where the running CLI lives and how it was started. */
+export interface RuntimeLocation {
+    packageDir: string;
+    /** process.argv[1], not symlink-resolved. */
+    entrypoint?: string;
+    execPath: string;
+    isBunRuntime: boolean;
+    platform: NodeJS.Platform;
+}
+/** Side effects needed to decide whether the running copy can upgrade itself. */
+export interface SelfUpdateEnvironment {
+    homedir: string;
+    readCommandOutput: (command: string) => string | undefined;
+    isWritable: (dir: string) => boolean;
+}
+export interface InstallPlan {
+    kind: 'install';
+    method: InstallMethod;
+    packageDir: string;
+    command: string;
+    /** package.json to read after installing, reached through the global root. */
+    packageJsonPath: string;
+}
+export interface ManualPlan {
+    kind: 'manual';
+    method: InstallMethod;
+    packageDir: string;
+    instruction: string;
+}
+export type SelfUpdatePlan = InstallPlan | ManualPlan;
+export declare function getRuntimeLocation(): RuntimeLocation;
 /**
- * Detects how the CLI was installed by checking global package lists
- * for each supported package manager.
+ * Detects the package manager from the location of the running code
+ * (same rules as Pi's detectInstallMethod).
  */
-export declare function detectMethod(): InstallMethod;
+export declare function detectInstallMethod(location?: RuntimeLocation): InstallMethod;
 /**
- * Async version of installation method detection to avoid blocking the event loop.
+ * Infers the npm prefix from a `<prefix>/lib/node_modules/bkper` layout.
+ * Windows prefixes look like project installs, so they are never inferred.
  */
-export declare function detectMethodAsync(commandRunner?: CommandRunner): Promise<InstallMethod>;
+export declare function inferNpmPrefix(packageDir: string, platform: NodeJS.Platform): string | undefined;
 /**
- * Checks whether a specific Bkper version is already installed globally.
+ * Returns the shell command that installs a version with a package manager.
  */
-export declare function isVersionInstalledAsync(method: InstallMethod, version: string, commandRunner?: CommandRunner): Promise<boolean>;
+export declare function getInstallCommand(method: InstallMethod, version: string, npmPrefix?: string): string | null;
 /**
- * Fetches the latest published version from the npm registry.
- * Returns null if the fetch fails.
+ * Decides whether the running copy can safely upgrade itself: it must be
+ * inside its package manager's global root and writable. Otherwise returns
+ * the manual instruction to show. Never suggests sudo.
  */
-export declare function fetchLatestVersion(): Promise<string | null>;
+export declare function getSelfUpdatePlan(version: string, location?: RuntimeLocation, environment?: SelfUpdateEnvironment): SelfUpdatePlan;
 /**
- * Returns the shell command to upgrade the CLI for a given install method and version.
+ * Reads a package version from disk, bypassing the module cache.
  */
-export declare function getUpgradeCommand(method: InstallMethod, version: string): string | null;
+export declare function readInstalledVersion(packageJsonPath: string): string | undefined;
 /**
- * Executes the upgrade to the specified version using the given install method.
- * Throws if the upgrade command fails.
+ * Runs an install command synchronously. BKPER_AUTOUPDATE_COMMAND replaces
+ * the command (for tests) but never the safety checks that lead here.
  */
-export declare function executeUpgrade(method: InstallMethod, version: string): void;
+export declare function runInstallCommand(command: string): void;
 /**
- * Starts the upgrade in a detached background process.
+ * Fetches the latest published version from the npm registry.
+ * Returns null if the fetch fails.
  */
-export declare function startDetachedUpgrade(method: InstallMethod, version: string, commandStarter?: DetachedCommandStarter): void;
+export declare function fetchLatestVersion(timeoutMs?: number): Promise<string | null>;
 //# sourceMappingURL=installation.d.ts.map

package/lib/upgrade/installation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installation.d.ts","sourceRoot":"","sources":["../../src/upgrade/installation.ts"],"names":[],"mappings":"AAMA,4CAA4C;AAC5C,eAAO,MAAM,OAAO,EAAE,MAAoB,CAAC;AAK3C,sCAAsC;AACtC,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;AAE/D,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AACpF,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAwC/D;;;GAGG;AACH,wBAAgB,YAAY,IAAI,aAAa,CAkB5C;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACnC,aAAa,GAAE,aAAoC,GACpD,OAAO,CAAC,aAAa,CAAC,CAaxB;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CACzC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,MAAM,EACf,aAAa,GAAE,aAAoC,GACpD,OAAO,CAAC,OAAO,CAAC,CAoBlB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBjE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWvF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAS3E;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAChC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,MAAM,EACf,cAAc,GAAE,sBAAsD,GACvE,IAAI,CAUN"}
+{"version":3,"file":"installation.d.ts","sourceRoot":"","sources":["../../src/upgrade/installation.ts"],"names":[],"mappings":"AAUA,4CAA4C;AAC5C,eAAO,MAAM,OAAO,EAAE,MAAoB,CAAC;AAK3C,oFAAoF;AACpF,eAAO,MAAM,WAAW,EAAE,MAGzB,CAAC;AAEF,sCAAsC;AACtC,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;AAExE,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC7B;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC3D,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACxC;AAED,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,eAAe,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACvB,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,UAAU,CAAC;AAEtD,wBAAgB,kBAAkB,IAAI,eAAe,CAQpD;AAiCD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,GAAE,eAAsC,GAAG,aAAa,CAkBnG;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,GAAG,MAAM,GAAG,SAAS,CAWhG;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC7B,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACnB,MAAM,GAAG,IAAI,CAgBf;AA+FD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC7B,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,eAAsC,EAChD,WAAW,GAAE,qBAAyD,GACvE,cAAc,CA6ChB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOhF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAGvD;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,SAAS,SAAO,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBjF"}