Files
TREK/server/src/nest/plugins/runtime/plugin-sdk.ts
T
Maurice 4b0986e2c6 style(plugins): keep the runtime and the SDK within their size baselines
The plugin data engine added three lines to each; six comments that wrapped past 120 columns now fit in one.
2026-11-17 14:53:24 +01:00

1026 lines
61 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* The plugin API as the isolated child implements it, its own copy of the trek-plugin-sdk
* types (plugin-sdk's test/host-types.test-d.ts holds the two to the same names and members).
* PURE: no server imports, zero external deps. Every ctx method is plumbing that turns a call
* into an RPC message to the host; the child holds no db handle, no secrets, no network.
*/
/** Mirrors the published package's constant — bumped on any breaking API change. */
export { PLUGIN_API_VERSION } from '../protocol/envelope';
export interface PluginContext {
readonly id: string;
/** `scope:'instance'` settings, secrets decrypted, frozen at activation; a field nobody
* set resolves to its manifest `default` (settings-defaults.ts). */
readonly config: Readonly<Record<string, unknown>>;
/** The ACTING USER's own value for one of this plugin's `scope:'user'` settings fields
* (decrypted host-side), or the field's manifest `default` when they never set it.
* Undefined for a field with neither, and in a userless context (job/onLoad) — fall
* back to `config` (the admin-owned instance settings) there. */
settings: {
get(key: string): Promise<unknown>;
};
db: {
query<T = unknown>(sql: string, ...args: unknown[]): Promise<T[]>;
exec(sql: string, ...args: unknown[]): Promise<{ changes: number }>;
migrate(id: string, sql: string): Promise<{ applied: boolean }>;
/** The engine your SQL runs on: 'sqlite' (the default), or 'postgres' when TREK runs on Postgres. */
engine(): Promise<'sqlite' | 'postgres'>;
/** Run several statements atomically on your OWN db — all commit or all roll
* back. Each op is one statement; reads see the batch's own earlier writes.
* A read returns `{ rows }`, a write `{ changes }`. Max 100 statements. */
tx(ops: Array<{ sql: string; args?: unknown[] }>): Promise<{ results: Array<{ changes?: number; rows?: unknown[] }> }>;
};
trips: {
// `asUserId` is accepted for source compatibility but IGNORED by the host —
// trip reads are always membership-checked against the authenticated user of
// the current invocation (the request's `req.user`), which the plugin cannot
// override. Only reachable from a route handler (a user context); a job has
// no user and its trip reads are refused.
getById(tripId: number, asUserId?: number): Promise<unknown>;
getPlaces(tripId: number, asUserId?: number): Promise<unknown[]>;
/** Hydrated like the REST list: each row carries `endpoints`, `day_positions` + the day/place joins. */
getReservations(tripId: number, asUserId?: number): Promise<unknown[]>;
/** The trip's days with their `assignments` + `notes_items` (the planner GET's shape). Needs 'db:read:trips'. */
getDays(tripId: number): Promise<unknown[]>;
/** The trip's lodging blocks (day_accommodations) with joined place fields. Needs 'db:read:trips'. */
getAccommodations(tripId: number): Promise<unknown[]>;
/** Every trip the acting user owns or is a member of (for dashboards/aggregates). Needs 'db:read:trips'. */
listMine(): Promise<unknown[]>;
/** Update trip fields (title/dates/currency/reminder_days/...); needs 'db:write:trips' + the acting user's 'trip_edit' permission. */
update(tripId: number, input: Record<string, unknown>): Promise<unknown>;
/** Create a new trip owned by the acting user (importers). `title` required. Needs 'db:create:trips' + the acting user's 'trip_create'. */
create(input: { title: string; description?: string; start_date?: string; end_date?: string; currency?: string; reminder_days?: number; day_count?: number }): Promise<unknown>;
/** The trip's member roster (id + display fields only). Membership-checked. Needs 'db:read:trips'. */
members(tripId: number): Promise<unknown[]>;
/** Add a user to a trip (GRANTS ACCESS — its own permission). Needs 'db:write:members' + the acting user's 'member_manage'. */
addMember(tripId: number, userId: number): Promise<{ joined: boolean; tripId: number }>;
/** Remove a member from a trip (not the owner). Needs `db:write:members` + member_manage. */
removeMember(tripId: number, userId: number): Promise<{ removed: boolean }>;
};
// Reservations (bookings). `listMine` reads across every accessible trip (needs
// 'db:read:trips'); create/update/delete need 'db:write:reservations' + the acting
// user's 'reservation_edit' permission, and reuse the app's accommodation/budget/
// notification side effects 1:1.
reservations: {
/** Every reservation across the acting user's accessible trips. Needs 'db:read:trips'. */
listMine(): Promise<unknown[]>;
/** Create a booking on a trip. An `endpoints` array (from/to/stop legs for flights,
* trains, ferries) is persisted with it. Needs 'db:write:reservations' + 'reservation_edit'. */
create(tripId: number, input: Record<string, unknown>): Promise<unknown>;
/** Update a booking on a trip. `endpoints` semantics: omitted = keep, [] = delete all,
* array = replace (endpoint ids are NOT stable). Needs 'db:write:reservations' + 'reservation_edit'. */
update(tripId: number, reservationId: number, input: Record<string, unknown>): Promise<unknown>;
/** Delete a booking from a trip. Needs 'db:write:reservations' + 'reservation_edit'. */
delete(tripId: number, reservationId: number): Promise<{ deleted: boolean }>;
};
// Lodging blocks (day_accommodations): a hotel span from a start day to an end day.
// Reads ride on 'db:read:trips' (ctx.trips.getAccommodations); writes need
// 'db:write:accommodations' + the acting user's 'day_edit' permission (like the
// REST path — accommodations live in the day service, not the bookings one).
// Creating one auto-creates its partner hotel reservation, exactly like the app.
accommodations: {
create(tripId: number, input: { place_id: number; start_day_id: number; end_day_id: number; check_in?: string | null; check_in_end?: string | null; check_out?: string | null; confirmation?: string | null; notes?: string | null }): Promise<unknown>;
update(tripId: number, accommodationId: number, input: Record<string, unknown>): Promise<unknown>;
delete(tripId: number, accommodationId: number): Promise<{ deleted: boolean }>;
};
// Read-only views of other trip subsystems (#1429 eco). Membership-checked like
// `trips`; each needs its own db:read:* scope.
packing: {
/** A trip's packing items (hydrated bags/assignees). Needs 'db:read:packing'. */
list(tripId: number): Promise<unknown[]>;
/** Add a packing item (owner = acting user). Needs 'db:write:packing' + 'packing_edit'. */
create(tripId: number, input: { name: string; category?: string; checked?: boolean; weight_grams?: number | null; bag_id?: number | null; quantity?: number; is_private?: boolean; visibility?: 'common' | 'personal' | 'shared'; recipient_ids?: number[] }): Promise<unknown>;
/** Update a packing item. Needs 'db:write:packing' + 'packing_edit'. */
update(tripId: number, itemId: number, input: Record<string, unknown>): Promise<unknown>;
/** Delete a packing item. Needs 'db:write:packing' + 'packing_edit'. */
delete(tripId: number, itemId: number): Promise<{ deleted: boolean }>;
/**
* List/create/update/delete packing bags + set members (no privacy). Bag methods need
* 'db:write:packing' + the acting user's 'packing_edit' trip permission — except this
* one: listBags is a read, but the envelope still gates it on the write scope
* (intentional — bags are the write-side structure; packing.list is the read surface).
*/
listBags(tripId: number): Promise<unknown[]>;
createBag(tripId: number, input: { name: string; color?: string; weight_limit_grams?: number }): Promise<unknown>;
updateBag(tripId: number, bagId: number, input: Record<string, unknown>): Promise<unknown>;
deleteBag(tripId: number, bagId: number): Promise<{ deleted: boolean }>;
setBagMembers(tripId: number, bagId: number, userIds: number[]): Promise<unknown>;
};
files: {
/** A trip's files, trash excluded. Needs 'db:read:files'. */
list(tripId: number): Promise<unknown[]>;
/** A file's bytes as base64 (10MB cap; trashed files refused). Needs 'db:read:files:content'. Returns { name, mimetype, size, content_base64 }. */
getContent(tripId: number, fileId: number): Promise<{ name: string; mimetype: string; size: number; content_base64: string }>;
/** Store base64 content as a trip file (10MB cap, blocked extensions refused). Needs 'db:write:files' + 'file_upload'. */
create(tripId: number, input: { name: string; content_base64: string; mimetype?: string; description?: string; place_id?: number; reservation_id?: number }): Promise<unknown>;
/** Link an existing file to a same-trip reservation/place/assignment. Needs 'db:write:files' + 'file_edit'. */
createLink(tripId: number, fileId: number, opts: { reservation_id?: number; assignment_id?: number; place_id?: number }): Promise<unknown>;
/** Update a file's description/links. Needs 'db:write:files' + 'file_edit'. */
update(tripId: number, fileId: number, input: { description?: string; place_id?: number | null; reservation_id?: number | null }): Promise<unknown>;
/** Move a file to the trash. Needs 'db:write:files' + 'file_delete'. */
softDelete(tripId: number, fileId: number): Promise<{ deleted: boolean }>;
};
/** Collab content (notes/polls/chat). Reads need 'db:read:collab'; writes need 'db:write:collab' + the acting user's 'collab_edit'. Both need the Collab addon. */
collab: {
/** A trip's collab notes (hydrated with author + attachments). Needs 'db:read:collab'. */
listNotes(tripId: number): Promise<unknown[]>;
/** A trip's polls (with options + voters). Needs 'db:read:collab'. */
listPolls(tripId: number): Promise<unknown[]>;
/** A trip's chat messages: newest 100, oldest first; `before` pages back from a message. Needs 'db:read:collab'. */
listMessages(tripId: number, before?: number): Promise<unknown[]>;
createNote(tripId: number, input: { title: string; content?: string; category?: string; color?: string; website?: string; pinned?: boolean }): Promise<unknown>;
createPoll(tripId: number, input: { question: string; options: unknown[]; multiple?: boolean; deadline?: string }): Promise<unknown>;
votePoll(tripId: number, pollId: number, optionIndex: number): Promise<unknown>;
createMessage(tripId: number, text: string, replyTo?: number): Promise<unknown>;
};
/** Host-mediated notification. The plugin supplies only target + plain text; the host
* owns delivery + preferences. Recipient is FORCED to the acting user (scope 'user',
* targetId = the acting user) or a trip they belong to (scope 'trip'). Needs 'notify:send'. */
notify: {
send(input: { title: string; body: string; link?: string; scope: 'user' | 'trip'; targetId: number }): Promise<{ sent: boolean }>;
};
/** Host-mediated LLM using the admin/user-configured provider — the plugin never holds a
* key. `complete` returns { text }; `extract` returns { results } for your JSON schema.
* Output is DATA: to persist it, push it through the gated write methods yourself. Needs 'ai:invoke'. */
ai: {
complete(prompt: string, system?: string): Promise<{ text: string }>;
extract(text: string, jsonSchema: object, prompt?: string): Promise<{ results: Record<string, unknown>[] }>;
};
/** Host-brokered outbound OAuth: a short-lived access token for the ACTING USER of a
* third-party service the host connected on their behalf (Settings → Plugins → Connect).
* Returns null when the user hasn't connected or in a userless context. The host holds
* the refresh token + client secret — you never see them. Needs 'oauth:client'. */
oauth: {
getAccessToken(): Promise<string | null>;
};
/** Persistent, userless scheduling — a future callback into your `scheduled` handler
* that survives restarts. Same risk class + grant as background jobs: needs 'jobs:run',
* runs with NO acting user (trip reads refused; own db + declared egress only). Caps:
* ≤100 tasks/plugin, ≤128-char name, ≤8 KB payload, recurring interval ≥60s, ≤1 year out.
* `set` is an upsert by name; `cancel` removes it. */
scheduler: {
/** Fire once at an absolute epoch-ms time. */
at(whenMs: number, name: string, payload?: unknown): Promise<{ scheduled: boolean }>;
/** Fire once after `ms` from now. */
in(ms: number, name: string, payload?: unknown): Promise<{ scheduled: boolean }>;
/** Fire repeatedly every `ms` (first fire after `ms`). */
every(ms: number, name: string, payload?: unknown): Promise<{ scheduled: boolean }>;
/** Cancel a scheduled task by name. */
cancel(name: string): Promise<{ cancelled: boolean }>;
};
/** Host weather cache by coordinates (+ optional YYYY-MM-DD). Tenant-free. Needs 'weather:read'. */
weather: {
get(lat: number, lng: number, date?: string): Promise<unknown>;
};
/** Exchange rates (tenant-free, cached upstream). Needs 'rates:read'. */
rates: {
/** A map of quote → rate relative to `base` (base 'EUR' → { USD: 1.08 }). `null` on an upstream failure. */
get(base: string): Promise<Record<string, number> | null>;
};
/** The global place-category reference list (read-only). Needs 'db:read:categories'. */
categories: {
list(): Promise<unknown[]>;
};
/** The acting user's own tags. Needs 'db:read:tags' (list) / 'db:write:tags' (create/update/delete). */
tags: {
list(): Promise<unknown[]>;
create(input: { name: string; color?: string }): Promise<unknown>;
update(tagId: number, input: { name?: string; color?: string }): Promise<unknown>;
delete(tagId: number): Promise<{ deleted: boolean }>;
};
/** A trip's to-dos. Needs 'db:read:todos' (list) / 'db:write:todos' + 'packing_edit' (create/update/delete). */
todos: {
list(tripId: number): Promise<unknown[]>;
create(tripId: number, input: { name: string; category?: string; due_date?: string; description?: string; assigned_user_id?: number; priority?: number }): Promise<unknown>;
update(tripId: number, todoId: number, input: Record<string, unknown>): Promise<unknown>;
delete(tripId: number, todoId: number): Promise<{ deleted: boolean }>;
};
// The acting user's OWN subsystem data across all their trips (not one trip), each
// gated on its addon being enabled — mirrors the addon's own REST/MCP readers.
journal: {
/** The acting user's journals. Needs 'db:read:journal' + the journey addon. */
listMine(): Promise<unknown[]>;
/** The entries of one of the acting user's journeys (photos/story/checkins), access-checked. Needs 'db:read:journal'. */
getEntries(journeyId: number): Promise<unknown[]>;
/** Create an entry on a journey the acting user can edit. Needs 'db:write:journal'. */
createEntry(journeyId: number, input: { entry_date: string; [k: string]: unknown }): Promise<unknown>;
/**
* Attach a photo to an entry, bytes included. Needs 'db:write:journal'.
*
* For an importer that holds an export archive: it has bytes, not a gallery
* photo to point at and not a provider asset. 'name' supplies the extension
* only, the stored filename is the host's. Images only, no SVG, 10MB decoded,
* and the operator's allowed-file-types setting applies.
*/
addEntryPhoto(entryId: number, input: { name: string; content_base64: string; caption?: string }): Promise<unknown>;
/** Update an entry (owner/contributor-gated). Needs 'db:write:journal'. */
updateEntry(entryId: number, input: Record<string, unknown>): Promise<unknown>;
/** Delete an entry (owner/contributor-gated). Needs 'db:write:journal'. */
deleteEntry(entryId: number): Promise<{ deleted: boolean }>;
/** Create a new journal owned by the acting user (an importer bootstraps the journal
* it then fills with entries). Needs 'db:write:journal'. */
createJourney(input: { title: string; subtitle?: string; trip_ids?: number[] }): Promise<unknown>;
/** Delete one of the acting user's journals. Needs 'db:write:journal'. */
deleteJourney(journeyId: number): Promise<{ deleted: boolean }>;
};
atlas: {
/** The acting user's visited countries + regions. Needs 'db:read:atlas' + the atlas addon. */
visited(): Promise<{ countries: unknown[]; regions: unknown[] }>;
/** The acting user's bucket-list items. Needs 'db:read:atlas'. */
bucketList(): Promise<unknown[]>;
/** Mark/unmark the ACTING USER's own visited countries/regions + bucket list. Needs 'db:write:atlas'. */
markCountry(code: string): Promise<unknown>;
unmarkCountry(code: string): Promise<unknown>;
markRegion(regionCode: string, countryCode: string, regionName?: string): Promise<unknown>;
unmarkRegion(regionCode: string): Promise<unknown>;
createBucketItem(input: { name: string; lat?: number; lng?: number; country_code?: string; notes?: string; target_date?: string }): Promise<unknown>;
deleteBucketItem(itemId: number): Promise<{ deleted: boolean }>;
};
vacay: {
/** The acting user's vacation plan data. Needs 'db:read:vacay' + the vacay addon. */
mine(): Promise<unknown>;
/** Toggle the ACTING USER's own PTO day on their active plan. Needs 'db:write:vacay'. */
toggleEntry(date: string): Promise<{ action: string }>;
/** Toggle a company holiday on the acting user's active plan. Needs 'db:write:vacay'. */
toggleCompanyHoliday(date: string, note?: string): Promise<{ action: string }>;
};
collections: {
/** The acting user's saved-place collections. Needs 'db:read:collections' + the collections addon. */
listMine(): Promise<unknown>;
/** One of the acting user's collections by id. Needs 'db:read:collections' + the collections addon. */
get(id: number): Promise<unknown>;
/** Collections write (per-collection role enforced by the service). Needs 'db:write:collections'. */
create(input: Record<string, unknown>): Promise<unknown>;
update(id: number, input: Record<string, unknown>): Promise<unknown>;
savePlace(input: Record<string, unknown>): Promise<unknown>;
copyToTrip(input: Record<string, unknown>): Promise<unknown>;
deletePlace(placeId: number): Promise<{ deleted: boolean }>;
};
daynotes: {
/** A day's notes on a trip (membership-checked). Needs 'db:read:daynotes'. */
list(tripId: number, dayId: number): Promise<unknown[]>;
/** Add a note to a day. Needs 'db:write:daynotes' + the acting user's 'day_edit'. */
create(tripId: number, dayId: number, input: Record<string, unknown>): Promise<unknown>;
/** Update a day note. Needs 'db:write:daynotes' + 'day_edit'. */
update(tripId: number, dayId: number, noteId: number, input: Record<string, unknown>): Promise<unknown>;
/** Delete a day note. Needs 'db:write:daynotes' + 'day_edit'. */
delete(tripId: number, dayId: number, noteId: number): Promise<{ deleted: boolean }>;
};
// "Costs" = budget items. Reads are membership-checked against the current
// invocation's user (like `trips`); `create` additionally needs the acting
// user's 'budget_edit' permission and the Costs addon enabled.
costs: {
getByTrip(tripId: number): Promise<unknown[]>;
listMine(): Promise<unknown[]>;
create(tripId: number, input: Record<string, unknown>): Promise<unknown>;
update(tripId: number, itemId: number, input: Record<string, unknown>): Promise<unknown>;
delete(tripId: number, itemId: number): Promise<{ deleted: boolean }>;
};
// Core planner writes (#1429). Each is membership-checked against the current
// invocation's user and needs the matching write scope + the app's edit
// permission (place_edit / day_edit / trip_edit). Route context only.
places: {
create(tripId: number, input: Record<string, unknown>): Promise<unknown>;
update(tripId: number, placeId: number, input: Record<string, unknown>): Promise<unknown>;
delete(tripId: number, placeId: number): Promise<{ deleted: boolean }>;
};
days: {
create(tripId: number, input: Record<string, unknown>): Promise<unknown>;
update(tripId: number, dayId: number, input: Record<string, unknown>): Promise<unknown>;
delete(tripId: number, dayId: number): Promise<{ deleted: boolean }>;
};
itinerary: {
assign(tripId: number, dayId: number, placeId: number, notes?: string | null): Promise<unknown>;
unassign(tripId: number, assignmentId: number): Promise<{ deleted: boolean }>;
};
// Your OWN namespaced key/value store attached to a trip/place/day (#1429), so
// you can enrich core entities without forking the schema. The entity must belong
// to a trip the current user can access. Values are JSON-serialisable.
meta: {
get(entityType: 'trip' | 'place' | 'day' | 'reservation' | 'accommodation', entityId: number, key: string): Promise<unknown>;
set(entityType: 'trip' | 'place' | 'day' | 'reservation' | 'accommodation', entityId: number, key: string, value: unknown): Promise<unknown>;
list(entityType: 'trip' | 'place' | 'day' | 'reservation' | 'accommodation', entityId: number): Promise<Record<string, unknown>>;
delete(entityType: 'trip' | 'place' | 'day' | 'reservation' | 'accommodation', entityId: number, key: string): Promise<{ deleted: boolean }>;
};
users: {
getById(id: number): Promise<unknown>;
};
ws: {
broadcastToTrip(tripId: number, event: string, data: Record<string, unknown>): Promise<void>;
broadcastToUser(userId: number, event: string, data: Record<string, unknown>): Promise<void>;
};
log: {
info(msg: string, meta?: Record<string, unknown>): void;
warn(msg: string, meta?: Record<string, unknown>): void;
error(msg: string, meta?: Record<string, unknown>): void;
};
/** Call a function another plugin exposes (must be a declared, satisfied dependency
* that lists `fn` in its manifest `capabilities.provides`). Runs as the current user. */
plugins: {
call(pluginId: string, fn: string, args?: unknown): Promise<unknown>;
};
/** Publish an event to dependents that subscribed to it (must be declared in this
* plugin's manifest `capabilities.emits`). Fire-and-forget. */
events: {
emit(name: string, payload?: unknown): void;
};
}
export interface PluginRequest {
method: string;
path: string;
query: Record<string, unknown>;
body: unknown;
/** Inbound headers — ONLY populated on `auth:false` routes (webhooks), and only an
* explicit, credential-free allowlist (signature + event headers from the common
* providers; never Cookie/Authorization/session). Empty on authenticated routes.
* Verify a provider signature against a secret you hold in `ctx.config`/`ctx.settings`. */
headers: Record<string, string>;
/** Raw body, base64, on `auth:false` routes only (else null): HMAC this, not the parsed `body`. */
rawBodyBase64?: string | null;
user: { id: number; username: string; isAdmin: boolean } | null;
}
export interface PluginResponse {
status: number;
headers?: Record<string, string>;
body?: unknown;
}
export interface PluginRoute {
method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
path: string;
auth?: boolean;
handler(req: PluginRequest, ctx: PluginContext): Promise<PluginResponse>;
}
export interface PluginJob {
id: string;
schedule: string;
handler(ctx: PluginContext): Promise<void>;
}
// ── Provider hooks (host→plugin): core asks a hook the plugin implements for data,
// gated by the matching hook:* permission. Each method also receives the per-
// invocation ctx, so any trip reads it makes bind to the authenticated user. ──
export interface Photo { id: string; title?: string; thumbnailUrl: string; fullUrl: string; takenAt?: string; }
export interface PhotoProvider {
search(query: string, opts: { page: number; limit: number }, ctx: PluginContext): Promise<{ photos: Photo[]; total: number; hasMore: boolean }>;
getById(id: string, ctx: PluginContext): Promise<Photo | null>;
}
/**
* A notification, already rendered by the host into the recipient's language.
* A channel plugin never touches i18n — it only delivers.
*/
export interface NotificationMessage {
/** The TREK event that produced this, e.g. `trip_invite`. */
event: string;
title: string;
body: string;
/** Absolute deep link back into TREK, when the event has one. */
url?: string;
tripName?: string;
}
/**
* Deliver TREK notifications over a channel TREK doesn't ship (Gotify, Pushover, …).
* Needs `hook:notification-channel`.
*
* Unlike every other hook, this one is HOST-initiated for an arbitrary recipient, so
* it runs WITHOUT an acting user: `ctx.settings.get()` returns undefined here and trip
* reads are refused. The recipient's own `scope:'user'` settings are decrypted by the
* host and handed to you as `config` instead — that is the only way to reach them, and
* it is why a channel plugin cannot enumerate the recipient's trips.
*/
export interface NotificationChannel {
send(msg: NotificationMessage, config: Record<string, unknown>, ctx: PluginContext): Promise<void>;
/** Backs the "Send test" button in the user's notification settings. */
test?(config: Record<string, unknown>, ctx: PluginContext): Promise<void>;
}
/**
* Result of a settings-page action. `message` is shown to the user beside the button
* (bounded + emoji-stripped host-side); throwing is equivalent to `{ ok: false }` with
* the error message.
*/
export interface PluginActionResult {
ok?: boolean;
message?: string;
}
export interface CalendarEvent { id: string; title: string; start: string; end: string; allDay: boolean; }
export interface CalendarSource {
getName(ctx: PluginContext): string;
getEvents(userId: number, start: string, end: string, ctx: PluginContext): Promise<CalendarEvent[]>;
}
/** One row of extra place info TREK renders natively (reviews/ratings/links/…). */
export interface PlaceDetailItem { label: string; value?: string; url?: string; }
export interface PlaceDetailProvider {
getDetails(placeId: number, ctx: PluginContext): Promise<PlaceDetailItem[]>;
}
/**
* A place a search provider found, in the shape the host turns into a search row.
*
* `rating` is the one field open data cannot answer, and the reason this hook exists:
* OpenStreetMap carries no ratings at all, so "the best one around here" needs an
* index that has them. Zero to five, the scale every such index uses.
*/
export interface SearchResultPlace {
/** Stable id in your own index. The host namespaces it as `plugin:<yourId>:<id>`. */
id?: string;
name: string;
lat: number;
lng: number;
address?: string;
rating?: number;
website?: string;
phone?: string;
category?: string;
description?: string;
}
/** What the host asks a search provider to look for. */
export interface SearchRequest {
query: string;
/** The most rows worth returning. The host caps it at 20 whatever it is asked for. */
limit: number;
/** The caller's language tag, for indexes that carry localized names. */
lang?: string;
/** Where the person is looking, when there is somewhere to bias toward. */
near?: { lat: number; lng: number };
/** Category search within a Roadtrip search rectangle. Older hosts omit these fields. */
category?: string;
bounds?: { south: number; west: number; north: number; east: number };
}
export interface SearchProvider {
search(request: SearchRequest, ctx: PluginContext): Promise<SearchResultPlace[]>;
/** Optional: the same question while it is typed (#2221). The host calls it only if the child reported it at load. */
suggest?(request: SearchRequest, ctx: PluginContext): Promise<SearchResultPlace[]>;
}
/**
* A POI category provider (#1781). Only the hook's name and call are spelled out here:
* the request and place shapes authors write against live once, in the published SDK.
* The child dispatches the hook by name, and the host re-validates every place it
* answers (plugin-pois.helpers.ts), so a second typed copy would guard nothing.
*/
export interface PoiCategoryProvider {
getPois(request: Readonly<Record<string, unknown>>, ctx: PluginContext): Promise<unknown[]>;
}
/** A validation/warning a plugin raises on a trip; TREK surfaces it in the planner. */
export interface TripWarning { level: 'info' | 'warning' | 'error'; message: string; dayId?: number; placeId?: number; }
export interface WarningProvider {
getWarnings(tripId: number, ctx: PluginContext): Promise<TripWarning[]>;
}
/** Host-rendered contributions into a native trip-planner view (reservations/places/day),
* keyed to an entity by id (#plugins). DECLARATIVE ONLY — a column is text/badge/link,
* an action is a labelled button whose target opens your sandboxed frame or calls a
* route. Never raw HTML/markup; the host renders + sanitizes everything. */
export type ContributionTone = 'default' | 'success' | 'warn' | 'danger';
/** An extra read-only cell/badge on an entity's row/card. */
export interface TableColumnContribution {
kind: 'column';
entityId: number; // the reservation/place/day id this attaches to
id: string; // stable per-contribution id (for React keys / dedupe)
label: string;
value?: string;
url?: string; // http/https/mailto only — the host rejects any other scheme
icon?: string; // a lucide icon name, resolved by the host
tone?: ContributionTone;
}
/** A labelled button on an entity's row/card; its target opens your sandboxed frame
* (`{kind:'frame', sub}`) or invokes one of your routes (`{kind:'route', method, sub}`). */
export interface TableActionContribution {
kind: 'action';
entityId: number;
id: string;
label: string;
icon?: string;
target: { kind: 'frame'; sub: string } | { kind: 'route'; method: 'GET' | 'POST'; sub: string };
}
export type TableContribution = TableColumnContribution | TableActionContribution;
export interface TableContributor {
/** `view` is one of 'reservations' | 'places' | 'day' | 'costs' | 'packing' | 'files'.
* Runs with the current user bound, on a short timeout; a slow/failing call is
* skipped, never fatal. */
getContributions(view: string, tripId: number, ctx: PluginContext): Promise<TableContribution[]>;
}
/** A bounded marker the host renders onto the trip map (#587). Declarative only —
* the host draws a Leaflet marker + popup; plugin JS never runs on the map canvas. */
export interface MapMarkerContribution {
id: string; // stable per-marker id (React key / dedupe)
lat: number; // -90..90
lng: number; // -180..180
label?: string; // short label shown in the popup title
popupText?: string; // one line of body text (host-sanitized, plain text)
url?: string; // http/https/mailto only — the host rejects any other scheme
icon?: string; // a lucide icon name, resolved by the host
tone?: ContributionTone;
}
export interface MapMarkerProvider {
/** Return markers to overlay on a trip's map. Runs with the current user bound,
* on a short timeout; the host caps the marker count and skips a failing call. */
getMarkers(tripId: number, ctx: PluginContext): Promise<MapMarkerContribution[]>;
}
/** One shape in a map layer. Declarative only — the host draws it; styling is the
* tone palette plus clamped numerics (width 1–8, opacity 0.05–1) and a dash enum. */
export interface MapLayerFeature {
type: 'polyline' | 'polygon' | 'circle';
points?: Array<[number, number]>; // [lat,lng] pairs — polyline (≥2) / polygon (≥3)
center?: [number, number]; // circle center [lat,lng]
radiusM?: number; // circle radius in metres (1..2,000,000)
tone?: ContributionTone;
width?: number; // stroke width, clamped 1..8 (default 3)
dash?: 'solid' | 'dash' | 'dot'; // stroke style (default solid)
opacity?: number; // stroke opacity, clamped 0.05..1 (default 0.8)
fill?: boolean; // polygon/circle: tint the inside (default true)
label?: string; // short tooltip text (≤80 chars)
}
/** A bounded vector overlay the host renders onto the trip map — a computed route,
* a reachable-range corridor, a zone. Complements mapMarkerProvider (points). */
export interface MapLayerContribution {
id: string; // stable per-layer id (React key / dedupe)
name?: string; // short layer name
features: MapLayerFeature[]; // host caps: 4 layers + 150 features + 8000 vertices per plugin
}
export interface MapLayerProvider {
/** Return layers to overlay on a trip's map. Runs with the current user bound,
* on a short timeout; the host caps the vertex budget and skips a failing call. */
getLayers(tripId: number, ctx: PluginContext): Promise<MapLayerContribution[]>;
}
/** One waypoint of a route request — a located stop of the day being routed. */
export interface RouteWaypoint {
lat: number;
lng: number;
name?: string; // the stop's display name, when known
placeId?: number; // the TREK place behind this stop, when it is one
}
/** What the planner asks a routeProvider to route. */
export interface RouteRequest {
tripId: number;
dayId: number | null; // the selected day, when the request is day-scoped
profile: string; // one of the plugin's declared capabilities.routeProfiles ids
waypoints: RouteWaypoint[]; // 2..30 located stops, in visit order
}
/** One leg of the returned route — between consecutive request waypoints. */
export interface RouteLeg {
distance: number; // metres
duration: number; // seconds (driving + any stop time you fold into the leg)
note?: string; // short text shown on the leg connector (e.g. "25 min charge"), ≤120 chars
}
/** An intermediate stop on the returned route (a charging stop, a rest area). */
export interface RouteViaPoint {
lat: number;
lng: number;
label?: string; // short marker text, ≤80 chars
tone?: ContributionTone;
dwellSeconds?: number; // planned time at the stop (0..86400)
}
/** A computed route. The host validates it whole: coordinates are range-checked
* (≤10000 vertices), legs must be exactly waypoints-1 entries, vias are capped
* at 40 — a malformed result is discarded and the planner falls back to straight
* lines, like an OSRM outage. */
export interface RouteProviderResult {
coordinates: Array<[number, number]>; // [lat,lng] polyline of the whole route
distance: number; // metres, whole route
duration: number; // seconds, whole route
legs: RouteLeg[];
viaPoints?: RouteViaPoint[];
}
export interface RouteProvider {
/** Route the given waypoints under one of the plugin's declared profiles.
* Runs with the current user bound, on a 20 s timeout (room for an external
* solver via declared egress); a failing call falls back to straight lines. */
getRoute(request: RouteRequest, ctx: PluginContext): Promise<RouteProviderResult>;
}
/** A time contribution the host renders into the day plan — "35 min charging at
* this stop", "45 min security before this flight". Anchored to an assignment or
* reservation row (or the start/end of a day); `minutes` also counts into the
* day's route-footer total. */
export interface DayScheduleContribution {
id: string; // stable per-item id (React key / dedupe)
dayId: number; // must be a day of the requested trip
assignmentId?: number; // anchor under this itinerary place row…
reservationId?: number; // …or under this booking row…
position?: 'start' | 'end'; // …or at the start/end of the day (default 'end')
minutes?: number; // planned time, 1..1440 — shown and totalled
label: string; // short text (≤120 chars)
tone?: ContributionTone;
}
export interface DayScheduleProvider {
/** Return schedule contributions for a trip's days. Runs with the current user
* bound, on a short timeout; the host caps the item count and skips a failing
* call. */
getSchedule(tripId: number, ctx: PluginContext): Promise<DayScheduleContribution[]>;
}
/** A colour the host paints into one day card in the Plan sidebar (and into that day's
* mobile chip) — so a trip split into legs shows its leg membership while you scroll
* the itinerary. A region takes a `tone` from the shared palette or the plugin's own
* `#rrggbb` `color` (exactly six hex digits — anything else is ignored); either way
* the host picks the alpha per theme and per region and clamps a colour's lightness,
* so the tint always lands as a readable wash. The card has three separately tintable
* regions; the `tone`/`color` shorthands fill every region not named, and `color` wins
* over `tone` at the same level. The regions follow the DESKTOP card — mobile honours
* only the badge (as the day chip). */
export interface DayTintContribution {
dayId: number; // must be a day of the requested trip
tone?: ContributionTone; // shorthand for every region not named below
color?: string; // own-colour shorthand, `#rrggbb` only
badgeTone?: ContributionTone; // the day-number badge (and the mobile day chip)
badgeColor?: string;
headerTone?: ContributionTone; // the day header row
headerColor?: string;
activityTone?: ContributionTone; // the expanded activity list
activityColor?: string;
label?: string; // optional tooltip on the day (≤60 chars)
}
export interface DayTintProvider {
/** Return one entry per day you want coloured. Runs with the current user bound, on
* a short timeout; a failing call is skipped. A day takes at most one contribution,
* resolved whole: within your own list the first entry for a day wins, and across
* plugins the first granted provider wins, so a day never flickers between two
* colours and two plugins can never each own part of one card. */
getDayTints(tripId: number, ctx: PluginContext): Promise<DayTintContribution[]>;
}
/** A text-only section the host appends to a trip's PDF export. Declarative only —
* plain strings the host lays out and escapes; no markup ever reaches the document. */
export interface PdfSection {
title: string; // section heading (capped at 120 chars)
paragraphs?: string[]; // body text — ≤20 paragraphs of ≤2000 chars each
table?: { headers: string[]; rows: string[][] }; // simple table — ≤8 headers, ≤50 rows
}
export interface PdfSectionProvider {
/** Return sections to append to a trip's PDF export. Runs with the current user
* bound, on a short timeout; the host caps counts/lengths and skips a failing call. */
getSections(tripId: number, ctx: PluginContext): Promise<PdfSection[]>;
}
/** One country in an Atlas tint layer. `code` is ISO-3166 alpha-2 (uppercased by the host). */
export interface AtlasLayerCountry { code: string; tone?: ContributionTone; label?: string; }
/** A country tint layer the host draws over the Atlas world map (wishlists, advisories, …). */
export interface AtlasLayer {
id: string; // stable per-layer id (React key / dedupe)
name?: string; // short layer name
countries: AtlasLayerCountry[]; // ≤300 countries per layer
}
export interface AtlasLayerProvider {
/** Return tint layers for the ACTING USER's Atlas map. User-scoped — the host binds
* the current user; the hook takes no target parameter. Runs on a short timeout;
* the host caps the layer/country counts and skips a failing call. */
getLayers(ctx: PluginContext): Promise<AtlasLayer[]>;
}
/** One row of extra info TREK renders under a journal entry (same shape as PlaceDetailItem). */
export interface JournalEntryRow { label: string; value?: string; url?: string; }
export interface JournalEntryProvider {
/** Return rows for a journal entry. Runs with the current user bound, on a short
* timeout; the host caps the row count and skips a failing call. */
getRows(entryId: number, ctx: PluginContext): Promise<JournalEntryRow[]>;
}
/** One badge the host renders on a dashboard trip card (declarative primitives only). */
export interface TripCardContribution {
tripId: number; id: string; label: string; value?: string; icon?: string; tone?: ContributionTone; url?: string;
}
export interface TripCardProvider {
/** Return badges for the dashboard trip cards on screen. `tripIds` are those cards
* (each access-checked for the acting user). Runs with the current user bound, on a
* short timeout; the host caps the badge count and skips a failing call. */
getCards(tripIds: number[], ctx: PluginContext): Promise<TripCardContribution[]>;
}
/** A core-event subscription (#1429 eco). Handlers run with NO user (like a job).
* Needs 'events:subscribe'. */
export interface PluginEventSubscription {
on: string; // a core event name (e.g. 'place:created', 'day:updated') or '*' for all
// `entity` = the event family (e.g. 'reservation'); `entityId` = WHICH entity changed,
// when known. `snapshot` = a whitelisted field view of the changed entity, delivered
// ONLY when this plugin also holds the family's db:read:* grant (db:read:trips for
// place/day/reservation/accommodation/assignment/trip, db:read:costs for budget,
// db:read:packing for packing, db:read:daynotes for dayNote, db:read:files for file).
// It never carries user ids, private packing items or secrets; delete/reorder/bulk
// events have none. There is still no acting user — a trip read from the handler is
// refused, so beyond the snapshot the id tells you what to react to, not what it
// contains.
handler(payload: { event: string; tripId: number; entity?: string; entityId?: number; snapshot?: Record<string, unknown> }, ctx: PluginContext): Promise<void> | void;
}
/** A function this plugin exposes to its dependents (declared in capabilities.provides). */
export type PluginExport = (args: unknown, ctx: PluginContext) => Promise<unknown> | unknown;
/** A subscription to another plugin's event. Authorized by declaring that plugin as a
* dependency; the handler runs with NO user and receives the emitter's payload. */
export interface PluginSubscription {
plugin: string;
event: string;
handler(payload: unknown, ctx: PluginContext): Promise<void> | void;
}
/**
* Publishes MCP tools on TREK's own MCP server, so an assistant can call into
* the plugin as the requesting user. Requires the `mcp:tools` permission.
*
* `tools` lists which of the tools declared in `capabilities.mcpTools` this
* build actually implements. The host advertises the intersection of the two:
* the manifest is signed and re-consented, this list is not, so a tool the
* manifest never declared is ignored rather than trusted.
*
* `callTool` receives the plugin-local name, without the `plugin_<id>_` prefix
* the tool is advertised under. Return anything JSON-serialisable; the host
* wraps it into an MCP result envelope, and a throw becomes a tool error the
* assistant can read and recover from.
*/
export interface McpToolProvider {
tools: string[];
callTool(call: { name: string; args: unknown }, ctx: PluginContext): Promise<unknown> | unknown;
}
export interface PluginDefinition {
onLoad?(ctx: PluginContext): Promise<void> | void;
onUnload?(ctx: PluginContext): Promise<void> | void;
routes?: PluginRoute[];
jobs?: PluginJob[];
/** Handles a callback registered via ctx.scheduler (userless, like a job). The
* `name` identifies which scheduled task fired; `payload` is what you passed. */
scheduled?(input: { name: string; payload: unknown }, ctx: PluginContext): Promise<void> | void;
/** GDPR erasure: a TREK account was deleted — remove everything you hold about it
* from your OWN db. Userless (no acting user). Needs `hook:user-data`. The host
* calls this durably (queued, retried until it succeeds), so make it idempotent. */
deleteUserData?(input: { userId: number }, ctx: PluginContext): Promise<void> | void;
/** GDPR portability: return the data you hold about a user (own db only), as a
* JSON-serialisable value the host aggregates. Userless. Needs `hook:user-data`. */
exportUserData?(input: { userId: number }, ctx: PluginContext): Promise<unknown> | unknown;
/**
* Buttons on the plugin's settings forms ("Test connection", "Sync now", "Purge
* cache"). The key must match an entry in the manifest's `actions`; that entry's
* `scope` decides WHERE the button renders — `'user'` (default) on the user Settings
* tab, `'instance'` in the admin instance-settings dialog.
*
* USER-INITIATED either way, so unlike the notificationChannel hook there IS an acting
* user — the person who clicked (a user, or an admin for an instance action).
* `ctx.settings.get()` returns THEIR value, `ctx.config` is the instance config, and
* trip reads are membership-checked against them.
*/
actions?: Record<string, (ctx: PluginContext) => Promise<PluginActionResult | void> | PluginActionResult | void>;
events?: PluginEventSubscription[];
hooks?: {
photoProvider?: PhotoProvider;
calendarSource?: CalendarSource;
placeDetailProvider?: PlaceDetailProvider;
searchProvider?: SearchProvider;
poiCategoryProvider?: PoiCategoryProvider;
warningProvider?: WarningProvider;
tableContributor?: TableContributor;
mapMarkerProvider?: MapMarkerProvider;
mapLayerProvider?: MapLayerProvider;
routeProvider?: RouteProvider;
dayScheduleProvider?: DayScheduleProvider;
dayTintProvider?: DayTintProvider;
pdfSectionProvider?: PdfSectionProvider;
atlasLayerProvider?: AtlasLayerProvider;
journalEntryProvider?: JournalEntryProvider;
tripCardProvider?: TripCardProvider;
notificationChannel?: NotificationChannel;
mcpToolProvider?: McpToolProvider;
};
/** Functions exposed to dependents (names must match manifest capabilities.provides). */
exports?: Record<string, PluginExport>;
/** Subscriptions to other plugins' events (each `plugin` must be a declared dependency). */
subscriptions?: PluginSubscription[];
}
/** Identity helper: gives authors types + a stable shape. A plain object works too. */
export function definePlugin(def: PluginDefinition): PluginDefinition {
return def;
}
/** Transport the child entry wires to process.send / message correlation. */
export interface ChildTransport {
rpc(method: string, params: Record<string, unknown>): Promise<unknown>;
emit(topic: string, data: unknown): void;
}
/**
* Build the ctx the plugin's handlers receive — every method is an RPC call.
* `invocationId` (the host's reqId for the route/job currently being handled) is
* attached to trip reads as `_inv` so the host can bind the acting user to THIS
* invocation. It is undefined for the load-time ctx (onLoad), where trip reads
* have no user and are refused.
*/
export function createPluginContext(
id: string,
config: Record<string, unknown>,
t: ChildTransport,
invocationId?: string,
): PluginContext {
return {
id,
config: Object.freeze({ ...config }),
settings: {
get: (key) => (t.rpc('settings.get', { key, _inv: invocationId }) as Promise<{ value: unknown }>).then((r) => r?.value),
},
db: {
query: (sql, ...args) => t.rpc('db.query', { sql, args }) as Promise<never[]>,
exec: (sql, ...args) => t.rpc('db.exec', { sql, args }) as Promise<{ changes: number }>,
migrate: (mid, sql) => t.rpc('db.migrate', { id: mid, sql }) as Promise<{ applied: boolean }>,
tx: (ops) => t.rpc('db.tx', { ops }) as Promise<{ results: Array<{ changes?: number; rows?: unknown[] }> }>,
engine: () => (t.rpc('db.engine', {}) as Promise<{ engine: 'sqlite' | 'postgres' }>).then((r) => r.engine),
},
trips: {
getById: (tripId) => t.rpc('trips.getById', { tripId, _inv: invocationId }),
getPlaces: (tripId) => t.rpc('trips.getPlaces', { tripId, _inv: invocationId }) as Promise<unknown[]>,
getReservations: (tripId) => t.rpc('trips.getReservations', { tripId, _inv: invocationId }) as Promise<unknown[]>,
getDays: (tripId) => t.rpc('trips.getDays', { tripId, _inv: invocationId }) as Promise<unknown[]>,
getAccommodations: (tripId) => t.rpc('trips.getAccommodations', { tripId, _inv: invocationId }) as Promise<unknown[]>,
listMine: () => t.rpc('trips.listMine', { _inv: invocationId }) as Promise<unknown[]>,
update: (tripId, input) => t.rpc('trips.update', { tripId, input, _inv: invocationId }),
create: (input) => t.rpc('trips.create', { input, _inv: invocationId }),
members: (tripId) => t.rpc('trips.members', { tripId, _inv: invocationId }) as Promise<unknown[]>,
addMember: (tripId, userId) => t.rpc('trips.addMember', { tripId, userId, _inv: invocationId }) as Promise<{ joined: boolean; tripId: number }>,
removeMember: (tripId, userId) => t.rpc('trips.removeMember', { tripId, userId, _inv: invocationId }) as Promise<{ removed: boolean }>,
},
reservations: {
listMine: () => t.rpc('reservations.listMine', { _inv: invocationId }) as Promise<unknown[]>,
create: (tripId, input) => t.rpc('reservations.create', { tripId, input, _inv: invocationId }),
update: (tripId, reservationId, input) => t.rpc('reservations.update', { tripId, reservationId, input, _inv: invocationId }),
delete: (tripId, reservationId) => t.rpc('reservations.delete', { tripId, reservationId, _inv: invocationId }) as Promise<{ deleted: boolean }>,
},
accommodations: {
create: (tripId, input) => t.rpc('accommodations.create', { tripId, input, _inv: invocationId }),
update: (tripId, accommodationId, input) => t.rpc('accommodations.update', { tripId, accommodationId, input, _inv: invocationId }),
delete: (tripId, accommodationId) => t.rpc('accommodations.delete', { tripId, accommodationId, _inv: invocationId }) as Promise<{ deleted: boolean }>,
},
packing: {
list: (tripId) => t.rpc('packing.list', { tripId, _inv: invocationId }) as Promise<unknown[]>,
create: (tripId, input) => t.rpc('packing.create', { tripId, input, _inv: invocationId }),
update: (tripId, itemId, input) => t.rpc('packing.update', { tripId, itemId, input, _inv: invocationId }),
delete: (tripId, itemId) => t.rpc('packing.delete', { tripId, itemId, _inv: invocationId }) as Promise<{ deleted: boolean }>,
listBags: (tripId) => t.rpc('packing.listBags', { tripId, _inv: invocationId }) as Promise<unknown[]>,
createBag: (tripId, input) => t.rpc('packing.createBag', { tripId, input, _inv: invocationId }),
updateBag: (tripId, bagId, input) => t.rpc('packing.updateBag', { tripId, bagId, input, _inv: invocationId }),
deleteBag: (tripId, bagId) => t.rpc('packing.deleteBag', { tripId, bagId, _inv: invocationId }) as Promise<{ deleted: boolean }>,
setBagMembers: (tripId, bagId, userIds) => t.rpc('packing.setBagMembers', { tripId, bagId, userIds, _inv: invocationId }),
},
files: {
list: (tripId) => t.rpc('files.list', { tripId, _inv: invocationId }) as Promise<unknown[]>,
getContent: (tripId, fileId) => t.rpc('files.getContent', { tripId, fileId, _inv: invocationId }) as Promise<{ name: string; mimetype: string; size: number; content_base64: string }>,
create: (tripId, input) => t.rpc('files.create', { tripId, input, _inv: invocationId }),
createLink: (tripId, fileId, opts) => t.rpc('files.createLink', { tripId, fileId, opts, _inv: invocationId }),
update: (tripId, fileId, input) => t.rpc('files.update', { tripId, fileId, input, _inv: invocationId }),
softDelete: (tripId, fileId) => t.rpc('files.softDelete', { tripId, fileId, _inv: invocationId }) as Promise<{ deleted: boolean }>,
},
collab: {
listNotes: (tripId) => t.rpc('collab.listNotes', { tripId, _inv: invocationId }) as Promise<unknown[]>,
listPolls: (tripId) => t.rpc('collab.listPolls', { tripId, _inv: invocationId }) as Promise<unknown[]>,
listMessages: (tripId, before) => t.rpc('collab.listMessages', { tripId, before, _inv: invocationId }) as Promise<unknown[]>,
createNote: (tripId, input) => t.rpc('collab.createNote', { tripId, input, _inv: invocationId }),
createPoll: (tripId, input) => t.rpc('collab.createPoll', { tripId, input, _inv: invocationId }),
votePoll: (tripId, pollId, optionIndex) => t.rpc('collab.votePoll', { tripId, pollId, optionIndex, _inv: invocationId }),
createMessage: (tripId, text, replyTo) => t.rpc('collab.createMessage', { tripId, text, replyTo, _inv: invocationId }),
},
notify: {
send: (input) => t.rpc('notify.send', { input, _inv: invocationId }) as Promise<{ sent: boolean }>,
},
ai: {
complete: (prompt, system) => t.rpc('ai.complete', { prompt, system, _inv: invocationId }) as Promise<{ text: string }>,
extract: (text, jsonSchema, prompt) => t.rpc('ai.extract', { text, jsonSchema, prompt, _inv: invocationId }) as Promise<{ results: Record<string, unknown>[] }>,
},
oauth: {
getAccessToken: () => (t.rpc('oauth.getToken', { _inv: invocationId }) as Promise<{ accessToken: string | null }>).then((r) => r?.accessToken ?? null),
},
scheduler: {
at: (whenMs, name, payload) => t.rpc('scheduler.set', { name, dueAt: whenMs, payload }) as Promise<{ scheduled: boolean }>,
in: (ms, name, payload) => t.rpc('scheduler.set', { name, dueAt: Date.now() + ms, payload }) as Promise<{ scheduled: boolean }>,
every: (ms, name, payload) => t.rpc('scheduler.set', { name, dueAt: Date.now() + ms, everyMs: ms, payload }) as Promise<{ scheduled: boolean }>,
cancel: (name) => t.rpc('scheduler.cancel', { name }) as Promise<{ cancelled: boolean }>,
},
weather: {
get: (lat, lng, date) => t.rpc('weather.get', { lat, lng, date, _inv: invocationId }),
},
rates: {
get: (base) => t.rpc('rates.get', { base, _inv: invocationId }) as Promise<Record<string, number> | null>,
},
categories: {
list: () => t.rpc('categories.list', { _inv: invocationId }) as Promise<unknown[]>,
},
tags: {
list: () => t.rpc('tags.list', { _inv: invocationId }) as Promise<unknown[]>,
create: (input) => t.rpc('tags.create', { input, _inv: invocationId }),
update: (tagId, input) => t.rpc('tags.update', { tagId, input, _inv: invocationId }),
delete: (tagId) => t.rpc('tags.delete', { tagId, _inv: invocationId }) as Promise<{ deleted: boolean }>,
},
todos: {
list: (tripId) => t.rpc('todos.list', { tripId, _inv: invocationId }) as Promise<unknown[]>,
create: (tripId, input) => t.rpc('todos.create', { tripId, input, _inv: invocationId }),
update: (tripId, todoId, input) => t.rpc('todos.update', { tripId, todoId, input, _inv: invocationId }),
delete: (tripId, todoId) => t.rpc('todos.delete', { tripId, todoId, _inv: invocationId }) as Promise<{ deleted: boolean }>,
},
journal: {
listMine: () => t.rpc('journal.listMine', { _inv: invocationId }) as Promise<unknown[]>,
getEntries: (journeyId) => t.rpc('journal.getEntries', { journeyId, _inv: invocationId }) as Promise<unknown[]>,
createEntry: (journeyId, input) => t.rpc('journal.createEntry', { journeyId, input, _inv: invocationId }),
addEntryPhoto: (entryId, input) => t.rpc('journal.addEntryPhoto', { entryId, input, _inv: invocationId }),
updateEntry: (entryId, input) => t.rpc('journal.updateEntry', { entryId, input, _inv: invocationId }),
deleteEntry: (entryId) => t.rpc('journal.deleteEntry', { entryId, _inv: invocationId }) as Promise<{ deleted: boolean }>,
createJourney: (input) => t.rpc('journal.createJourney', { input, _inv: invocationId }),
deleteJourney: (journeyId) => t.rpc('journal.deleteJourney', { journeyId, _inv: invocationId }) as Promise<{ deleted: boolean }>,
},
atlas: {
visited: () => t.rpc('atlas.visited', { _inv: invocationId }) as Promise<{ countries: unknown[]; regions: unknown[] }>,
bucketList: () => t.rpc('atlas.bucketList', { _inv: invocationId }) as Promise<unknown[]>,
markCountry: (code) => t.rpc('atlas.markCountry', { code, _inv: invocationId }),
unmarkCountry: (code) => t.rpc('atlas.unmarkCountry', { code, _inv: invocationId }),
markRegion: (regionCode, countryCode, regionName) => t.rpc('atlas.markRegion', { regionCode, countryCode, regionName, _inv: invocationId }),
unmarkRegion: (regionCode) => t.rpc('atlas.unmarkRegion', { regionCode, _inv: invocationId }),
createBucketItem: (input) => t.rpc('atlas.createBucketItem', { input, _inv: invocationId }),
deleteBucketItem: (itemId) => t.rpc('atlas.deleteBucketItem', { itemId, _inv: invocationId }) as Promise<{ deleted: boolean }>,
},
vacay: {
mine: () => t.rpc('vacay.mine', { _inv: invocationId }),
toggleEntry: (date) => t.rpc('vacay.toggleEntry', { date, _inv: invocationId }) as Promise<{ action: string }>,
toggleCompanyHoliday: (date, note) => t.rpc('vacay.toggleCompanyHoliday', { date, note, _inv: invocationId }) as Promise<{ action: string }>,
},
collections: {
listMine: () => t.rpc('collections.listMine', { _inv: invocationId }),
get: (id) => t.rpc('collections.get', { id, _inv: invocationId }),
create: (input) => t.rpc('collections.create', { input, _inv: invocationId }),
update: (id, input) => t.rpc('collections.update', { id, input, _inv: invocationId }),
savePlace: (input) => t.rpc('collections.savePlace', { input, _inv: invocationId }),
copyToTrip: (input) => t.rpc('collections.copyToTrip', { input, _inv: invocationId }),
deletePlace: (placeId) => t.rpc('collections.deletePlace', { placeId, _inv: invocationId }) as Promise<{ deleted: boolean }>,
},
daynotes: {
list: (tripId, dayId) => t.rpc('daynotes.list', { tripId, dayId, _inv: invocationId }) as Promise<unknown[]>,
create: (tripId, dayId, input) => t.rpc('daynotes.create', { tripId, dayId, input, _inv: invocationId }),
update: (tripId, dayId, noteId, input) => t.rpc('daynotes.update', { tripId, dayId, noteId, input, _inv: invocationId }),
delete: (tripId, dayId, noteId) => t.rpc('daynotes.delete', { tripId, dayId, noteId, _inv: invocationId }) as Promise<{ deleted: boolean }>,
},
costs: {
getByTrip: (tripId) => t.rpc('costs.getByTrip', { tripId, _inv: invocationId }) as Promise<unknown[]>,
listMine: () => t.rpc('costs.listMine', { _inv: invocationId }) as Promise<unknown[]>,
create: (tripId, input) => t.rpc('costs.create', { tripId, input, _inv: invocationId }),
update: (tripId, itemId, input) => t.rpc('costs.update', { tripId, itemId, input, _inv: invocationId }),
delete: (tripId, itemId) => t.rpc('costs.delete', { tripId, itemId, _inv: invocationId }) as Promise<{ deleted: boolean }>,
},
places: {
create: (tripId, input) => t.rpc('places.create', { tripId, input, _inv: invocationId }),
update: (tripId, placeId, input) => t.rpc('places.update', { tripId, placeId, input, _inv: invocationId }),
delete: (tripId, placeId) => t.rpc('places.delete', { tripId, placeId, _inv: invocationId }) as Promise<{ deleted: boolean }>,
},
days: {
create: (tripId, input) => t.rpc('days.create', { tripId, input, _inv: invocationId }),
update: (tripId, dayId, input) => t.rpc('days.update', { tripId, dayId, input, _inv: invocationId }),
delete: (tripId, dayId) => t.rpc('days.delete', { tripId, dayId, _inv: invocationId }) as Promise<{ deleted: boolean }>,
},
itinerary: {
assign: (tripId, dayId, placeId, notes) => t.rpc('itinerary.assign', { tripId, dayId, placeId, notes, _inv: invocationId }),
unassign: (tripId, assignmentId) => t.rpc('itinerary.unassign', { tripId, assignmentId, _inv: invocationId }) as Promise<{ deleted: boolean }>,
},
meta: {
get: (entityType, entityId, key) => t.rpc('meta.get', { entityType, entityId, key, _inv: invocationId }),
set: (entityType, entityId, key, value) => t.rpc('meta.set', { entityType, entityId, key, value, _inv: invocationId }),
list: (entityType, entityId) => t.rpc('meta.list', { entityType, entityId, _inv: invocationId }) as Promise<Record<string, unknown>>,
delete: (entityType, entityId, key) => t.rpc('meta.delete', { entityType, entityId, key, _inv: invocationId }) as Promise<{ deleted: boolean }>,
},
users: {
getById: (uid) => t.rpc('users.getById', { id: uid, _inv: invocationId }),
},
ws: {
// _inv binds the invocation's acting user host-side; without it the host can't
// membership-check the broadcast and refuses every call (the capability was dead).
broadcastToTrip: async (tripId, event, data) => {
await t.rpc('ws.broadcastToTrip', { tripId, event, data, _inv: invocationId });
},
broadcastToUser: async (userId, event, data) => {
await t.rpc('ws.broadcastToUser', { userId, event, data, _inv: invocationId });
},
},
log: {
info: (msg, meta) => t.emit('log', { level: 'info', msg, meta }),
warn: (msg, meta) => t.emit('log', { level: 'warn', msg, meta }),
error: (msg, meta) => t.emit('log', { level: 'error', msg, meta }),
},
plugins: {
call: (pluginId, fn, args) => t.rpc('plugins.call', { targetId: pluginId, fn, args, _inv: invocationId }),
},
events: {
// Fire-and-forget by contract, but the host CAN reject (undeclared event name,
// rate-limit). The rejection must not escape — a detached rejection crashes the child
// and terminally disables the plugin over one bad emit — but swallowing it silently
// left an author with no way to discover that `emits` was missing from the manifest.
// Surface it on the plugin's own log stream instead.
emit: (name, payload) => {
t.rpc('events.emit', { event: name, payload }).catch((e: unknown) => {
t.emit('log', {
level: 'warn',
msg: `events.emit("${name}") was rejected by the host: ${e instanceof Error ? e.message : String(e)}`,
meta: { event: name },
});
});
},
},
};
}