/** * 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>; /** 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; }; db: { query(sql: string, ...args: unknown[]): Promise; 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; getPlaces(tripId: number, asUserId?: number): Promise; /** Hydrated like the REST list: each row carries `endpoints`, `day_positions` + the day/place joins. */ getReservations(tripId: number, asUserId?: number): Promise; /** The trip's days with their `assignments` + `notes_items` (the planner GET's shape). Needs 'db:read:trips'. */ getDays(tripId: number): Promise; /** The trip's lodging blocks (day_accommodations) with joined place fields. Needs 'db:read:trips'. */ getAccommodations(tripId: number): Promise; /** Every trip the acting user owns or is a member of (for dashboards/aggregates). Needs 'db:read:trips'. */ listMine(): Promise; /** Update trip fields (title/dates/currency/reminder_days/...); needs 'db:write:trips' + the acting user's 'trip_edit' permission. */ update(tripId: number, input: Record): Promise; /** 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; /** The trip's member roster (id + display fields only). Membership-checked. Needs 'db:read:trips'. */ members(tripId: number): Promise; /** 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; /** 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): Promise; /** 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): Promise; /** 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; update(tripId: number, accommodationId: number, input: Record): Promise; 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; /** 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; /** Update a packing item. Needs 'db:write:packing' + 'packing_edit'. */ update(tripId: number, itemId: number, input: Record): Promise; /** 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; createBag(tripId: number, input: { name: string; color?: string; weight_limit_grams?: number }): Promise; updateBag(tripId: number, bagId: number, input: Record): Promise; deleteBag(tripId: number, bagId: number): Promise<{ deleted: boolean }>; setBagMembers(tripId: number, bagId: number, userIds: number[]): Promise; }; files: { /** A trip's files, trash excluded. Needs 'db:read:files'. */ list(tripId: number): Promise; /** 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; /** 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; /** 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; /** 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; /** A trip's polls (with options + voters). Needs 'db:read:collab'. */ listPolls(tripId: number): Promise; /** 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; createNote(tripId: number, input: { title: string; content?: string; category?: string; color?: string; website?: string; pinned?: boolean }): Promise; createPoll(tripId: number, input: { question: string; options: unknown[]; multiple?: boolean; deadline?: string }): Promise; votePoll(tripId: number, pollId: number, optionIndex: number): Promise; createMessage(tripId: number, text: string, replyTo?: number): Promise; }; /** 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[] }>; }; /** 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; }; /** 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; }; /** 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 | null>; }; /** The global place-category reference list (read-only). Needs 'db:read:categories'. */ categories: { list(): Promise; }; /** The acting user's own tags. Needs 'db:read:tags' (list) / 'db:write:tags' (create/update/delete). */ tags: { list(): Promise; create(input: { name: string; color?: string }): Promise; update(tagId: number, input: { name?: string; color?: string }): Promise; 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; create(tripId: number, input: { name: string; category?: string; due_date?: string; description?: string; assigned_user_id?: number; priority?: number }): Promise; update(tripId: number, todoId: number, input: Record): Promise; 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; /** The entries of one of the acting user's journeys (photos/story/checkins), access-checked. Needs 'db:read:journal'. */ getEntries(journeyId: number): Promise; /** 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; /** * 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; /** Update an entry (owner/contributor-gated). Needs 'db:write:journal'. */ updateEntry(entryId: number, input: Record): Promise; /** 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; /** 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; /** Mark/unmark the ACTING USER's own visited countries/regions + bucket list. Needs 'db:write:atlas'. */ markCountry(code: string): Promise; unmarkCountry(code: string): Promise; markRegion(regionCode: string, countryCode: string, regionName?: string): Promise; unmarkRegion(regionCode: string): Promise; createBucketItem(input: { name: string; lat?: number; lng?: number; country_code?: string; notes?: string; target_date?: string }): Promise; deleteBucketItem(itemId: number): Promise<{ deleted: boolean }>; }; vacay: { /** The acting user's vacation plan data. Needs 'db:read:vacay' + the vacay addon. */ mine(): Promise; /** 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; /** One of the acting user's collections by id. Needs 'db:read:collections' + the collections addon. */ get(id: number): Promise; /** Collections write (per-collection role enforced by the service). Needs 'db:write:collections'. */ create(input: Record): Promise; update(id: number, input: Record): Promise; savePlace(input: Record): Promise; copyToTrip(input: Record): Promise; 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; /** Add a note to a day. Needs 'db:write:daynotes' + the acting user's 'day_edit'. */ create(tripId: number, dayId: number, input: Record): Promise; /** Update a day note. Needs 'db:write:daynotes' + 'day_edit'. */ update(tripId: number, dayId: number, noteId: number, input: Record): Promise; /** 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; listMine(): Promise; create(tripId: number, input: Record): Promise; update(tripId: number, itemId: number, input: Record): Promise; 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): Promise; update(tripId: number, placeId: number, input: Record): Promise; delete(tripId: number, placeId: number): Promise<{ deleted: boolean }>; }; days: { create(tripId: number, input: Record): Promise; update(tripId: number, dayId: number, input: Record): Promise; delete(tripId: number, dayId: number): Promise<{ deleted: boolean }>; }; itinerary: { assign(tripId: number, dayId: number, placeId: number, notes?: string | null): Promise; 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; set(entityType: 'trip' | 'place' | 'day' | 'reservation' | 'accommodation', entityId: number, key: string, value: unknown): Promise; list(entityType: 'trip' | 'place' | 'day' | 'reservation' | 'accommodation', entityId: number): Promise>; delete(entityType: 'trip' | 'place' | 'day' | 'reservation' | 'accommodation', entityId: number, key: string): Promise<{ deleted: boolean }>; }; users: { getById(id: number): Promise; }; ws: { broadcastToTrip(tripId: number, event: string, data: Record): Promise; broadcastToUser(userId: number, event: string, data: Record): Promise; }; log: { info(msg: string, meta?: Record): void; warn(msg: string, meta?: Record): void; error(msg: string, meta?: Record): 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; }; /** 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; 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; /** 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; body?: unknown; } export interface PluginRoute { method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'; path: string; auth?: boolean; handler(req: PluginRequest, ctx: PluginContext): Promise; } export interface PluginJob { id: string; schedule: string; handler(ctx: PluginContext): Promise; } // ── 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; } /** * 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, ctx: PluginContext): Promise; /** Backs the "Send test" button in the user's notification settings. */ test?(config: Record, ctx: PluginContext): Promise; } /** * 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; } /** 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; } /** * 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::`. */ 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; /** 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; } /** * 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>, ctx: PluginContext): Promise; } /** 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; } /** 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; } /** 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; } /** 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; } /** 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; } /** 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; } /** 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; } /** 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; } /** 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; } /** 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; } /** 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; } /** 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 }, ctx: PluginContext): Promise | void; } /** A function this plugin exposes to its dependents (declared in capabilities.provides). */ export type PluginExport = (args: unknown, ctx: PluginContext) => Promise | 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; } /** * 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__` 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; } export interface PluginDefinition { onLoad?(ctx: PluginContext): Promise | void; onUnload?(ctx: PluginContext): Promise | 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; /** 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; /** 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; /** * 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 Promise | 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; /** 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): Promise; 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, 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, 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, getReservations: (tripId) => t.rpc('trips.getReservations', { tripId, _inv: invocationId }) as Promise, getDays: (tripId) => t.rpc('trips.getDays', { tripId, _inv: invocationId }) as Promise, getAccommodations: (tripId) => t.rpc('trips.getAccommodations', { tripId, _inv: invocationId }) as Promise, listMine: () => t.rpc('trips.listMine', { _inv: invocationId }) as Promise, 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, 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, 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, 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, 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, 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, listPolls: (tripId) => t.rpc('collab.listPolls', { tripId, _inv: invocationId }) as Promise, listMessages: (tripId, before) => t.rpc('collab.listMessages', { tripId, before, _inv: invocationId }) as Promise, 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[] }>, }, 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 | null>, }, categories: { list: () => t.rpc('categories.list', { _inv: invocationId }) as Promise, }, tags: { list: () => t.rpc('tags.list', { _inv: invocationId }) as Promise, 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, 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, getEntries: (journeyId) => t.rpc('journal.getEntries', { journeyId, _inv: invocationId }) as Promise, 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, 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, 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, listMine: () => t.rpc('costs.listMine', { _inv: invocationId }) as Promise, 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>, 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 }, }); }); }, }, }; }