@pitcher/js-api 1.29.0 → 1.31.0

package/lib/constants/translationLanguages.const.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Target languages offered by the content-translation feature.
+ *
+ * ⚠️ MIRROR — the single source of truth is
+ * `packages/next-core/src/services/translation/languages.ts`
+ * (`TRANSLATION_LANGUAGES`). next-core cannot be imported from canvas-ui or the
+ * admin client, so the list is duplicated here for the UI pickers only. Keep the
+ * `locale` values byte-identical with that file: the backend resolves the DeepL
+ * target code and the English language name from the locale we post, so a locale
+ * that exists here and not there is rejected by the route.
+ *
+ * The admin client imports this from `@pitcher/canvas-ui` rather than keeping a
+ * third copy, so there are exactly two lists to reconcile, never more.
+ *
+ * `label` is intentionally NOT an i18n key: language names are shown in their own
+ * language (the endonym), which is what every locale picker in the product does,
+ * and it keeps the list free of the dynamic-key lookups the i18n extractor strips.
+ * That is also what lets this list exceed the shipped locales without any i18n work.
+ *
+ * ⚠️ THE LITERAL ORDER IS THE DISPLAY ORDER. Entries are sorted by `label`, the
+ * string the admin actually reads: Latin alphabetically, then Greek, Cyrillic,
+ * Devanagari, Thai, Hangul, CJK, which is what `Intl.Collator` yields. Sorting by
+ * `locale` reads better in a diff and was the original order, but it only looked
+ * alphabetical by accident while the list was 14 Latin-ish languages — at 24 it put
+ * Suomi between Español and Français. The pickers do not sort, so this list must.
+ *
+ * ⚠️ These are NOT all platform UI locales. The original 14 were, which is why an
+ * older version of this comment said so; the 10 added on 2026-08-11 (cs, da, fi,
+ * hi, id, ko, nb, ru, sv, vi) have no `locale/<code>.json`. Translating CONTENT is
+ * not localising the PRODUCT, and nothing here loads a bundle from `locale`.
+ *
+ * ⚠️ Every entry must stay selectable — the admin client maps this list straight to
+ * Vuetify items with no `disabled` prop and no filtering, which is deliberate. Do
+ * not add a per-language disabled/beta flag; a language that cannot be served by
+ * both translation legs should not be in the list. That is why Arabic and Hebrew
+ * are absent despite DeepL supporting them: the product has no RTL rendering, so a
+ * translated canvas would lay out left-to-right.
+ */
+export interface TranslationLanguageOption {
+    /** Target-language key posted to the backend. NOT necessarily a shipped UI locale. */
+    locale: string;
+    /** Endonym shown in the picker. */
+    label: string;
+    /**
+     * English name of the language, used ONLY to make the picker searchable.
+     *
+     * ⚠️ Load-bearing for `filterable` pickers. Naive UI's default filter matches
+     * `option.label`, and `label` is the endonym — so without this an admin typing
+     * "swedish" gets "No data" for Svenska, and likewise for 9 other entries. The
+     * filter must be given explicitly and must test BOTH fields; see
+     * `translationLanguageOptions`.
+     */
+    englishName: string;
+    /** Uppercase suffix the backend appends to a translated record's name. */
+    suffix: string;
+}
+export declare const TRANSLATION_LANGUAGES: readonly TranslationLanguageOption[];
+/**
+ * Uppercase language suffix of a TRANSLATED record, read from the provenance stamp
+ * `metadata.pitcher.translation.language` that the duplicate-translate route writes.
+ * Returns undefined for an untranslated record or an unrecognised locale, so a caller
+ * can use the result directly as the "show a badge" condition.
+ */
+export declare function translatedLanguageSuffix(metadata: unknown): string | undefined;
+/**
+ * File extensions the row action and the upload picker offer.
+ *
+ * ⚠️ MIRROR — the source of truth is `DEEPL_SUPPORTED_EXTENSIONS` in
+ * `packages/next-core/src/services/deepl.service.ts`, which is what the
+ * `files/translate` route actually validates against. Every entry here MUST exist
+ * there, or the UI offers a translation the route answers with
+ * `400 invalid_request`.
+ *
+ * Legacy `.doc` and `.ppt` are deliberately absent: DeepL rejects the legacy
+ * binary formats, so offering them only produced that 400. The DeepL list is a
+ * superset (it also accepts `xlf`, `xliff`, `srt`); those stay out of the UI until
+ * there is a reason to surface localisation-interchange formats to admins, and a
+ * subset is safe in a way a superset is not.
+ */
+export declare const TRANSLATABLE_FILE_EXTENSIONS: readonly string[];
+export declare function isTranslatableFileExtension(extension?: string | null): boolean;
+/**
+ * Extension of a file record, resolved the way the route resolves it.
+ *
+ * ⚠️ MIRROR of `resolveExtension` in
+ * `packages/next-core/src/services/translation/translated-file.ts`: prefer
+ * `content_extension`, then `extension`, then parse the name. Keep the two in
+ * step — a gate that disagrees with the route either hides a supported file or
+ * offers one the route will reject.
+ *
+ * `content_extension` comes first because it is the closest thing the list
+ * payload has to the rendition, and it is nearer to what the route declares to
+ * DeepL. Resolving `original_extension` first offered the action for a
+ * PDF-converted deck as `pptx`, so the button appeared and the upload then
+ * failed on bytes that are a PDF.
+ *
+ * ⚠️ `content_extension` does NOT describe the bytes actually stored. It records
+ * the UPLOAD. Django derives the served rendition from `content_type` alone
+ * (`get_content_url`), which is why the route resolves from `content_url` and
+ * this gate can only approximate it. Do not restate the stronger claim: it was
+ * wrong, and believing it cost three defects on PIT-7916.
+ *
+ * ⚠️ The chain is deliberately LONGER than the route's, and `original_extension`
+ * must stay in it. The two read different payloads:
+ *
+ * - This gate runs over the **folder/list** payload, which carries ONLY
+ *   `original_extension` (verified against `GET /api/v1/folders/{id}/`: no
+ *   `content_extension`, no `extension`). Drop it here and every file in the
+ *   content browser resolves `''` and loses the action.
+ * - The route re-resolves from the **detail** payload
+ *   (`GET /api/v1/files/{id}/`), which always carries `content_extension`, so it
+ *   never needs the pre-conversion value and must not trust it.
+ *
+ * So a converted deck shows the action as `pptx` and then translates as `pdf`,
+ * which is correct in both places. The name parse survives as the last resort
+ * for records with no extension column at all.
+ */
+export declare function resolveFileExtension(file?: {
+    name?: string | null;
+    content_extension?: string | null;
+    extension?: string | null;
+    original_extension?: string | null;
+} | null): string;
+/**
+ * Naive UI / CSelect option shape for the language pickers.
+ *
+ * `englishName` rides along so a `filterable` picker can search it — see
+ * `translationLanguageFilter`, which such a picker MUST be given.
+ */
+export declare function translationLanguageOptions(): {
+    label: string;
+    englishName: string;
+    value: string;
+}[];
+/**
+ * Filter for a `filterable` language picker, matching the endonym OR the English name.
+ *
+ * ⚠️ Pass this explicitly. Naive UI's default filter tests `option.label` only, and
+ * `label` is the endonym, so the default silently returns "No data" for every
+ * language an English-speaking admin would type the name of: Čeština, Dansk, Suomi,
+ * हिन्दी, Bahasa Indonesia, 한국어, Norsk bokmål, Русский, Svenska, Tiếng Việt, plus
+ * Ελληνικά, 日本語, ไทย and 中文. That is 14 of 24, and it fails silently rather than
+ * visibly, which is why it went unnoticed while the list was small.
+ *
+ * Accent-insensitive on the pattern side too, so "cestina" finds Čeština.
+ */
+export declare function translationLanguageFilter(pattern: string, option: {
+    label?: string;
+    englishName?: string;
+}): boolean;

package/lib/constants/translationLanguages.const.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/main.lib.d.ts

@@ -86,6 +86,7 @@ export { default as CAssignedCanvasesManagement } from './components/assignedCan
 export { default as CAssignedCanvasesManagementToolbar } from './components/assignedCanvases/CAssignedCanvasesManagementToolbar.vue';
 export { default as useShareCanvas } from './components/savedCanvases/CSavedCanvasesManagementShareCanvas.use';
 export { getFreezeStatus, SYSTEM_EXCLUDED_TAGS, type FreezeStatus } from './components/savedCanvases/CSavedCanvasesManagement.use';
+export { buildMasterFromTemplatePayload, type MasterFromTemplatePayload, type MasterTemplateSource, } from './components/masterCanvases/masterFromTemplate.use';
 export { default as CConfigEditor } from './components/CConfigEditor/CConfigEditor.vue';
 export { default as CTableInput } from './components/CTableInput/CTableInput.vue';
 export { default as CTableTag } from './components/CTableTag/CTableTag.vue';
@@ -106,6 +107,7 @@ export { default as CFileViewer } from './components/CFileViewer/CFileViewer.vue
 export { default as CDetailPageSectionButtons } from './components/CDetailPageSectionButtons/CDetailPageSectionButtons.vue';
 export { default as CFullScreenLoader } from './components/CFullScreenLoader/CFullScreenLoader.vue';
 export { default as CGlobalLoader } from './components/CGlobalLoader/CGlobalLoader.vue';
+export { default as CGlobalLoaderMark } from './components/CGlobalLoader/CGlobalLoaderMark.vue';
 export { default as CFilesFolderDeleteDialogContent } from './components/CFilesFolderDeleteDialogContent/CFilesFolderDeleteDialogContent.vue';
 export { default as CCatalogIqSwitcher } from './components/CCatalogIqSwitcher/CCatalogIqSwitcher.vue';
 export { default as CCarousel } from './components/CCarousel/CCarousel.vue';
@@ -138,6 +140,9 @@ export { default as CanvasSelector } from './apps/canvas-selector/App.vue';
 export type { CanvasSelection } from './apps/canvas-selector/appTypes';
 export { default as NotesApp } from './apps/notes/NotesApp.vue';
 export { default as useNotesApp } from './apps/notes/composables/useNotesApp';
+export { useAccountNotes, accountNotesBucketKey, NOTES_APP_CONTENT_KEY } from './apps/notes/composables/useAccountNotes';
+export { useAccountOnlyNotesGate } from './apps/notes/composables/useAccountOnlyNotesGate';
+export { ACTIVE_SLIDE_NOTES_KEY, clearActiveSlideNotes, setActiveSlideNotes, useActiveSlideNotes, type ActiveSlideNotes, } from './apps/notes/composables/useActiveSlideNotes';
 export { default as AssetsManagerApp } from './apps/assets-manager/App.vue';
 export type { AppProps as AssetsManagerProps } from './apps/assets-manager/App.vue';
 export * as pptConversionSelector from './apps/ppt-conversion-selector/export';
@@ -178,6 +183,7 @@ export { usePolling } from './composables/usePolling';
 export { default as useBroadcastRouteChange } from './composables/useBroadcastRouteChange';
 export * from './plugins/vueQuery';
 export * from './apps/canvas-builder/util/canvas.util';
+export * from './apps/canvas-builder/util/completionWizard.util';
 export * from './apps/canvas-builder/util/tree';
 export * from './apps/canvas-builder/util/print.util';
 export * from './components/filters/filter.util';
@@ -267,6 +273,7 @@ export * from './constants/conventions.const';
 export * from './constants/config.const';
 export * from './constants/pitcherSettings.const';
 export * from './constants/appsDb.const';
+export * from './constants/translationLanguages.const';
 export * from './apps/canvas-builder/constants/theme.const';
 export * from './constants/roles.const';
 export type { RolePermissions } from './constants/roles.const';

package/lib/sdk/api/HighLevelApi.d.ts

@@ -122,9 +122,11 @@ export declare function createHighLevelApi(options?: ApiOptions): {
      * @returns {Promise<void>}
      */
     unsubscribe: () => Promise<any>;
+    postJsonWithTimeout<T>(url: string, body: unknown, accessToken: string, timeoutMs: number, label: string): Promise<T>;
     aiGetCapabilities(): Promise<import('../payload.types').AIRuntimeCapabilities>;
     aiComplete(payload: import('../payload.types').AICompletePayload): Promise<import('../payload.types').AICompleteResult>;
     piaSearchAnswer(payload: import('../payload.types').PiaSearchAnswerPayload): Promise<import('../payload.types').PiaSearchAnswerResult>;
+    weeklyFocusRank(payload: import('../payload.types').WeeklyFocusRankPayload): Promise<import('../payload.types').WeeklyFocusRankResult>;
     appsDbGetEntries(payload: import('../payload.types').AppsDbGetEntriesPayload): Promise<import('../payload.types').AppsDbEntriesResult>;
     appsDbUpsertEntry(payload: import('../payload.types').AppsDbUpsertEntryPayload): Promise<import('../payload.types').AppsDbEntry>;
     appsDbDeleteEntry(payload: import('../payload.types').AppsDbDeleteEntryPayload): Promise<void>;
@@ -147,7 +149,20 @@ export declare function createHighLevelApi(options?: ApiOptions): {
     updateCanvas(payload: import('../../main.lib').PatchedCanvasUpdateRequest & {
         id: import('../../main.lib').CanvasRetrieve["id"];
         instance_id?: import('../../main.lib').Instance["id"];
-        fields?: string;
+        fields
+        /**
+         * Make the entire CatalogIQ fullscreen.
+         *
+         * @example
+         * usePitcherApi().enterFullscreen()
+         */
+        ? /**
+         * Make the entire CatalogIQ fullscreen.
+         *
+         * @example
+         * usePitcherApi().enterFullscreen()
+         */: string;
+        lazy_sections?: boolean;
     }): Promise<import('../../main.lib').CanvasRetrieve>;
     updateCanvasIndicators(payload: {
         indicators: Record<string, import('../../main.lib').CanvasIndicator>;
@@ -157,11 +172,8 @@ export declare function createHighLevelApi(options?: ApiOptions): {
     getCanvas(payload: {
         id: import('../../main.lib').CanvasRetrieve["id"];
         fields?: string;
-        lazy_sections? /**
-         * Subscribe to updates.
-         *
-         * @returns {Promise<void>}
-         */: boolean;
+        lazy_sections?: boolean;
+        skip_error_toast?: boolean;
     }): Promise<import('../../main.lib').CanvasRetrieve>;
     getSectionsByIds(payload: {
         canvas_id: import('../../main.lib').CanvasRetrieve["id"];
@@ -174,6 +186,7 @@ export declare function createHighLevelApi(options?: ApiOptions): {
     }>;
     shareCanvas(payload: {
         id: import('../../main.lib').CanvasRetrieve["id"];
+        brand_id?: string;
     }): Promise<import('../../main.lib').SharedLink>;
     getCanvasRecommendedFiles(payload: {
         canvas_id: import('../../main.lib').CanvasRetrieve["id"];

package/lib/sdk/api/modules/ai.d.ts

@@ -1,4 +1,17 @@
-import { AICompletePayload, AICompleteResult, AIRuntimeCapabilities, PiaSearchAnswerPayload, PiaSearchAnswerResult } from '../../payload.types';
+import { AICompletePayload, AICompleteResult, AIRuntimeCapabilities, PiaSearchAnswerPayload, PiaSearchAnswerResult, WeeklyFocusRankPayload, WeeklyFocusRankResult } from '../../payload.types';
+/**
+ * POST JSON to a next-core route with a hard deadline, returning the parsed body.
+ * The shared scaffold behind the SDK's online AI calls (`piaSearchAnswer`,
+ * `weeklyFocusRank`).
+ *
+ * Bounds the WHOLE request including the body read: `fetch()` resolves on headers
+ * alone, so reading `.json()` INSIDE the timed window (and letting the abort
+ * cancel that read too — hence `clearTimeout` in `finally`) is what stops a
+ * response that stalls mid-body from hanging unbounded. `label` names the route
+ * in BOTH the non-2xx error (`<label> <status>`) and the timeout error, so each
+ * caller keeps its exact error strings.
+ */
+export declare function postJsonWithTimeout<T>(url: string, body: unknown, accessToken: string, timeoutMs: number, label: string): Promise<T>;
 /**
  * Capabilities of the AI completion runtime on the current platform.
  *
@@ -50,3 +63,32 @@ export declare function aiComplete(payload: AICompletePayload): Promise<AIComple
  * console.log(result.answer, result.cited_file_ids, result.source)
  */
 export declare function piaSearchAnswer(payload: PiaSearchAnswerPayload): Promise<PiaSearchAnswerResult>;
+/**
+ * Rank the rep's next-7-days meetings by how much preparation they need — the
+ * ONE high-level Weekly Focus call (PIT-7257), the `weekly_focus` AITask.
+ *
+ * The on-device path runs the prompt, window, parser and ordinal resolver from
+ * `@lib/ai-tasks/weekly-focus`; the online route runs next-core's parallel copy
+ * of the same logic. The two are kept in lockstep by matching test suites, not a
+ * shared import (see that module's header / ADR-002), so the two paths produce
+ * the same shape:
+ *
+ * - iOS with an available local model → `aiComplete` over the caller-supplied
+ *   meetings + account context. Unavailable models / unusable output fall through.
+ * - Otherwise → POST to the next-core Bedrock route.
+ *
+ * The model picks meetings by ORDINAL and the resolver maps them back to
+ * event_ids, dropping out-of-range ones — so a returned id can only come from
+ * the `meetings` passed in.
+ *
+ * This does NOT cache, lock or prewarm: an app that generates on a schedule (as
+ * pre-call-brief does) owns those mechanics and calls this underneath.
+ *
+ * @param {WeeklyFocusRankPayload} payload - The meetings + optional account context.
+ * @returns {Promise<WeeklyFocusRankResult>} - Ranking with the serving `source`.
+ *
+ * @example
+ * const focus = await api.weeklyFocusRank({ meetings, context })
+ * console.log(focus.hero, focus.top, focus.collapsed_count)
+ */
+export declare function weeklyFocusRank(payload: WeeklyFocusRankPayload): Promise<WeeklyFocusRankResult>;

package/lib/sdk/api/modules/ai.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/sdk/api/modules/appsDb.d.ts

@@ -2,7 +2,7 @@ import { AppsDbDeleteEntryPayload, AppsDbEntriesResult, AppsDbEntry, AppsDbGetEn
 /**
  * Lists AppsDB entries of a type, adapting to the platform:
  * - Web: GET to the next-core AppsDB REST API.
- * - iOS: reads the local offline mirror via the `appsdb_get_entries` bridge
+ * - Native (iPad or desktop): reads the local offline mirror via the `appsdb_get_entries` bridge
  *   request. Types not allowlisted in the `offline_appsdb_types` setting fail
  *   with `code = type_not_synced` and automatically fall back to the network.
  *
@@ -13,7 +13,7 @@ export declare function appsDbGetEntries(payload: AppsDbGetEntriesPayload): Prom
 /**
  * Creates or updates (deep-merges) an AppsDB entry, adapting to the platform:
  * - Web: POST (create) or PUT (update, when `id` is set) to the next-core AppsDB REST API.
- * - iOS: the `appsdb_upsert_entry` bridge request writes on the server and
+ * - Native (iPad or desktop): the `appsdb_upsert_entry` bridge request writes on the server and
  *   mirrors the authoritative result locally. Offline it rejects with
  *   `code = offline_write_not_supported` — AppsDB writes are online-only.
  *
@@ -28,7 +28,7 @@ export declare function appsDbUpsertEntry(payload: AppsDbUpsertEntryPayload): Pr
 /**
  * Deletes an AppsDB entry (soft delete server-side), adapting to the platform:
  * - Web: DELETE to the next-core AppsDB REST API.
- * - iOS: the `appsdb_delete_entry` bridge request deletes on the server and
+ * - Native (iPad or desktop): the `appsdb_delete_entry` bridge request deletes on the server and
  *   removes the entry from the local offline mirror. Offline it rejects with
  *   `code = offline_write_not_supported`.
  *
@@ -40,7 +40,7 @@ export declare function appsDbDeleteEntry(payload: AppsDbDeleteEntryPayload): Pr
  * Runs a PSQL (SQL-like) query against AppsDB: POST to the next-core
  * `/appsdb/psql` endpoint whenever the network is available.
  *
- * On iOS the local offline mirror (`appsdb_get_entries` + client-side
+ * On a native host the local offline mirror (`appsdb_get_entries` + client-side
  * evaluation of simple `field = literal` AND-chains) serves the query ONLY
  * while the device is offline, or when an online fetch fails at the
  * connection level. Online queries are always answered by the server: Hub

package/lib/sdk/api/modules/canvas.d.ts

@@ -44,6 +44,14 @@ export declare function updateCanvas(payload: PatchedCanvasUpdateRequest & {
     id: CanvasRetrieve['id'];
     instance_id?: Instance['id'];
     fields?: string;
+    /**
+     * Request the lazy "shell" on the PATCH response (section stubs +
+     * `section_ids` instead of expanded bodies). No-op unless the instance's
+     * `lazy_load_sections` setting is on (server-side double-gate). With a
+     * `fields` list that excludes `sections`, the response is byte-identical —
+     * only the server-side cost drops (PIT-7073).
+     */
+    lazy_sections?: boolean;
 }): Promise<CanvasRetrieve>;
 /**
  * Updates canvas indicators by canvas ID. It merges the passed object into existing canvas indicators adding new keys if they were empty and overriding pre-existing keys.
@@ -83,6 +91,8 @@ export declare function getCanvas(payload: {
     id: CanvasRetrieve['id'];
     fields?: string;
     lazy_sections?: boolean;
+    /** Suppress the host's error toast for best-effort reads (e.g. download-completion polling). */
+    skip_error_toast?: boolean;
 }): Promise<CanvasRetrieve>;
 /**
  * Batch-hydrate section bodies for a canvas fetched as a lazy shell.
@@ -115,8 +125,18 @@ export declare function getSectionsByIds(payload: {
 }): Promise<{
     sections: CanvasSection[];
 }>;
+/**
+ * Get (or create) the shared link for a canvas.
+ *
+ * `brand_id` (PIT-7682, optional) names an entry in the instance's `shared_link_brands` setting and
+ * only takes effect when the link is created. Omit it and the server uses the brand the rep last
+ * used on that instance, falling back to the instance default — the behaviour quick-share,
+ * bulk-share and API-created links get. A host that does not forward it (the iOS bridge today)
+ * therefore still produces a correctly branded link, just without the rep's per-share choice.
+ */
 export declare function shareCanvas(payload: {
     id: CanvasRetrieve['id'];
+    brand_id?: string;
 }): Promise<SharedLink>;
 export declare function getCanvasRecommendedFiles(payload: {
     canvas_id: CanvasRetrieve['id'];

package/lib/sdk/api/modules/ui/types.ui.d.ts

@@ -58,6 +58,13 @@ export declare const UI_MESSAGE_TYPES: {
 export declare const UI_NATIVE_MESSAGE_TYPES: readonly ["ui_app_set_data", "ui_app_update_data", "ui_canvas_updated"];
 export type UiBroadcastRequest = Record<string, any>;
 export type UiSelectContentRequest = {
+    /**
+     * Named sub-embedding of the content selector, forwarded verbatim to the selector app's
+     * `window.initialize` payload so ONE selector app can present itself differently per
+     * caller (PIT-7510: `ng-wizard` for the pitchdeck wizard). `embed_location` itself is set
+     * by the HOST and always wins, so a caller-specific context needs its own field.
+     */
+    embed_variant?: string;
     /** Array of selections */
     selections?: Selection[];
     content_type?: 'file' | 'slide' | 'content';
@@ -349,5 +356,23 @@ export interface UiOpenSharingSettingsResponse {
         allowed_domains?: string[];
         valid_until_days?: number | null;
         allow_download?: boolean;
+        /**
+         * PIT-7682 — id of an entry in the instance's `shared_link_brands` setting, present only when
+         * the rep made a deliberate pick in the sharing modal. The host collects it; the app that
+         * later creates the link (ng-emails-app's ShareBox POST) forwards it verbatim to
+         * `/shared-links`, which is the only place it means anything — the brand is baked into the
+         * short URL at creation. Absent means "no choice", and the API applies the brand the rep last
+         * used on the instance, then the instance default.
+         */
+        brand_id?: string;
     };
+    /**
+     * PIT-5865 — the name the rep typed for the ShareBox in the sharing modal, already resolved
+     * (blank fell back to the default timestamp name, and it is capped at 100 chars). Deliberately a
+     * SIBLING of `settings` rather than a field inside it: `settings` is stored verbatim by the
+     * calling app as its pending-ShareBox sharing settings and rides into saved drafts, so a canvas
+     * name has no business in there. Absent on older hosts — the caller falls back to its own
+     * default.
+     */
+    canvas_name?: string;
 }

package/lib/sdk/interfaces.d.ts

@@ -49,7 +49,18 @@ export interface OrgConfigResponse {
     sentry_region: 'us' | 'eu';
 }
 export interface PitcherEnv {
-    mode: 'WEB' | 'IOS' | 'WINDOWS' | 'ANDROID';
+    /**
+     * The HOST the web layer is running inside — `mode` IS the platform, one value per OS.
+     *
+     * `WEB` is the browser; everything else is a NATIVE shell with a JS bridge and an offline
+     * mirror (`IOS` the iPad, `MACOS`/`WINDOWS`/`ANDROID` the Tauri desktop/Android shell). Never
+     * write `mode === 'IOS'` to mean "native" — use `isNativeHost(mode)` (`@sdk/platform`), which
+     * is `mode !== 'WEB'` so a host newer than this bundle still takes the native branch. Values are
+     * only ever ADDED to this union — never renamed or removed, apps in the field compare them. `IOS` stays
+     * the right test only for iPad HARDWARE: MultipeerConnectivity (peer session), the Salesforce
+     * Mobile SDK's SmartStore, on-device inference — subsystems no other host has.
+     */
+    mode: 'WEB' | 'IOS' | 'WINDOWS' | 'ANDROID' | 'MACOS';
     pitcher: {
         token_claims: Record<string, any>;
         organization: PitcherOrg;
@@ -78,6 +89,25 @@ export interface PitcherEnv {
     ui_locale?: string;
     device_locale?: string;
     sync_badge_value?: number;
+    /**
+     * Bridge capabilities the running native host advertises (PIT-7682). Only web posts to the API
+     * directly and needs no capability check — every NATIVE host (`isNativeHost(env.mode)`) routes
+     * requests through its own bridge handlers.
+     *
+     * That includes the **Tauri desktop/Android shell** (`pitcher-impact-tauri-ng`), which reports
+     * its own build target as `mode` (`MACOS` / `WINDOWS` / `ANDROID`) and states what it supports
+     * here. A host that omits a token behaves exactly like an old iPad build — consumers that treat
+     * absent as unsupported degrade it safely — so gaining a capability means implementing the
+     * forwarding first.
+     *
+     * Tokens are `<request_type>.<field>`, e.g. `share_canvas.brand_id`. Feature-detect on them
+     * rather than on `version`: an older host omits the key entirely, so **absent must be treated as
+     * unsupported**. The shape is not guaranteed either — it crosses a bridge from native code — so
+     * check `Array.isArray` before `.includes`, or a string value substring-matches the gate open.
+     * Defined natively in `BridgeCapabilities` (pitcher-impact-ios-ng); the strings are a permanent
+     * contract because web builds in the wild keep checking them.
+     */
+    capabilities?: string[];
 }
 export interface PitcherAPI extends Emitter<ApiEventMap> {
     request(type: string, body: any, callback: () => any): Promise<PitcherResponse>;

package/lib/sdk/main.d.ts

@@ -1,6 +1,7 @@
 import { ApiOptions } from './interfaces';
 import { createHighLevelApi } from './api/HighLevelApi';
 export * from './interfaces';
+export * from './platform';
 export * from './payload.types';
 export * from './api/modules/ui/types.ui';
 export * from './api/modules/admin/types.admin';
@@ -9,8 +10,39 @@ export * from './peer-connectivity';
 export declare let highLevelApi: ReturnType<typeof createHighLevelApi>;
 /**
  * Check out the returned object documentation for the list of available methods.
+ *
+ * `options` CONFIGURES THE SHARED SINGLETON — it is not component-scoped. The
+ * host app is expected to pass them exactly once at boot (slotty does this in
+ * `api/client.ts`, supplying the Sentry `errorLogger` and the org's `fetchMode`).
+ *
+ * A call with NO options is a plain accessor and must never rebuild: canvas-ui
+ * has ~40 bare `usePitcherApi()` call sites (composables, comment components,
+ * `useBroadcastRouteChange` on every sidebar navigation). Rebuilding on those
+ * reset the singleton to `LowLevelApi`'s constructor defaults — dropping the
+ * host's `fetchMode` back to 'postmessage' and silently replacing the Sentry
+ * errorLogger with a no-op for the rest of the session. Because `highLevelApi`
+ * is an exported `let` with ESM live binding, every later importer picked up the
+ * downgraded instance. Each rebuild also registered another never-removed
+ * `window` 'message' listener and fired another `subscribe`, so listeners grew
+ * without bound.
+ *
+ * If you need different options for one call site, use `createScopedPitcherApi`
+ * — do not pass options here.
  */
 export declare function usePitcherApi(options?: ApiOptions): ReturnType<typeof createHighLevelApi>;
+/**
+ * A DEDICATED api instance for a call site that needs different options, without
+ * touching the shared singleton every other consumer holds.
+ *
+ * Inherits whatever the host configured (so the Sentry errorLogger and casing
+ * survive) and applies `options` on top.
+ *
+ * Each instance registers its own `window` 'message' listener and its own
+ * `subscribe`, so create ONE per call site at module scope — never inside a
+ * component `setup()`, which would leak a listener per mount. Responses are
+ * matched by callback id and unknown ids are ignored, so instances coexist.
+ */
+export declare function createScopedPitcherApi(options?: ApiOptions): ReturnType<typeof createHighLevelApi>;
 /**
  * API methods available in the CatalogIQ default UI.
  *
@@ -195,9 +227,11 @@ export declare function useApi(options?: ApiOptions): {
     broadcastToWebviews: (event: import('./interfaces').PitcherEvent) => Promise<any>;
     subscribe: () => Promise<any>;
     unsubscribe: () => Promise<any>;
+    postJsonWithTimeout<T>(url: string, body: unknown, accessToken: string, timeoutMs: number, label: string): Promise<T>;
     aiGetCapabilities(): Promise<import('./payload.types').AIRuntimeCapabilities>;
     aiComplete(payload: import('./payload.types').AICompletePayload): Promise<import('./payload.types').AICompleteResult>;
     piaSearchAnswer(payload: import('./payload.types').PiaSearchAnswerPayload): Promise<import('./payload.types').PiaSearchAnswerResult>;
+    weeklyFocusRank(payload: import('./payload.types').WeeklyFocusRankPayload): Promise<import('./payload.types').WeeklyFocusRankResult>;
     appsDbGetEntries(payload: import('./payload.types').AppsDbGetEntriesPayload): Promise<import('./payload.types').AppsDbEntriesResult>;
     appsDbUpsertEntry(payload: import('./payload.types').AppsDbUpsertEntryPayload): Promise<import('./payload.types').AppsDbEntry>;
     appsDbDeleteEntry(payload: import('./payload.types').AppsDbDeleteEntryPayload): Promise<void>;
@@ -221,6 +255,7 @@ export declare function useApi(options?: ApiOptions): {
         id: import('../main.lib').CanvasRetrieve["id"];
         instance_id?: import('../main.lib').Instance["id"];
         fields?: string;
+        lazy_sections?: boolean;
     }): Promise<import('../main.lib').CanvasRetrieve>;
     updateCanvasIndicators(payload: {
         indicators: Record<string, import('../main.lib').CanvasIndicator>;
@@ -231,6 +266,7 @@ export declare function useApi(options?: ApiOptions): {
         id: import('../main.lib').CanvasRetrieve["id"];
         fields?: string;
         lazy_sections?: boolean;
+        skip_error_toast?: boolean;
     }): Promise<import('../main.lib').CanvasRetrieve>;
     getSectionsByIds(payload: {
         canvas_id: import('../main.lib').CanvasRetrieve["id"];
@@ -243,6 +279,7 @@ export declare function useApi(options?: ApiOptions): {
     }>;
     shareCanvas(payload: {
         id: import('../main.lib').CanvasRetrieve["id"];
+        brand_id?: string;
     }): Promise<import('../main.lib').SharedLink>;
     getCanvasRecommendedFiles(payload: {
         canvas_id: import('../main.lib').CanvasRetrieve["id"];
@@ -499,9 +536,11 @@ export declare function useApi(options?: ApiOptions): {
         broadcastToWebviews: (event: import('./interfaces').PitcherEvent) => Promise<any>;
         subscribe: () => Promise<any>;
         unsubscribe: () => Promise<any>;
+        postJsonWithTimeout<T>(url: string, body: unknown, accessToken: string, timeoutMs: number, label: string): Promise<T>;
         aiGetCapabilities(): Promise<import('./payload.types').AIRuntimeCapabilities>;
         aiComplete(payload: import('./payload.types').AICompletePayload): Promise<import('./payload.types').AICompleteResult>;
         piaSearchAnswer(payload: import('./payload.types').PiaSearchAnswerPayload): Promise<import('./payload.types').PiaSearchAnswerResult>;
+        weeklyFocusRank(payload: import('./payload.types').WeeklyFocusRankPayload): Promise<import('./payload.types').WeeklyFocusRankResult>;
         appsDbGetEntries(payload: import('./payload.types').AppsDbGetEntriesPayload): Promise<import('./payload.types').AppsDbEntriesResult>;
         appsDbUpsertEntry(payload: import('./payload.types').AppsDbUpsertEntryPayload): Promise<import('./payload.types').AppsDbEntry>;
         appsDbDeleteEntry(payload: import('./payload.types').AppsDbDeleteEntryPayload): Promise<void>;
@@ -525,6 +564,7 @@ export declare function useApi(options?: ApiOptions): {
             id: import('../main.lib').CanvasRetrieve["id"];
             instance_id?: import('../main.lib').Instance["id"];
             fields?: string;
+            lazy_sections?: boolean;
         }): Promise<import('../main.lib').CanvasRetrieve>;
         updateCanvasIndicators(payload: {
             indicators: Record<string, import('../main.lib').CanvasIndicator>;
@@ -535,6 +575,7 @@ export declare function useApi(options?: ApiOptions): {
             id: import('../main.lib').CanvasRetrieve["id"];
             fields?: string;
             lazy_sections?: boolean;
+            skip_error_toast?: boolean;
         }): Promise<import('../main.lib').CanvasRetrieve>;
         getSectionsByIds(payload: {
             canvas_id: import('../main.lib').CanvasRetrieve["id"];
@@ -547,6 +588,7 @@ export declare function useApi(options?: ApiOptions): {
         }>;
         shareCanvas(payload: {
             id: import('../main.lib').CanvasRetrieve["id"];
+            brand_id?: string;
         }): Promise<import('../main.lib').SharedLink>;
         getCanvasRecommendedFiles(payload: {
             canvas_id: import('../main.lib').CanvasRetrieve["id"];
@@ -749,9 +791,11 @@ export declare function useApi(options?: ApiOptions): {
     broadcastToWebviews: (event: import('./interfaces').PitcherEvent) => Promise<any>;
     subscribe: () => Promise<any>;
     unsubscribe: () => Promise<any>;
+    postJsonWithTimeout<T>(url: string, body: unknown, accessToken: string, timeoutMs: number, label: string): Promise<T>;
     aiGetCapabilities(): Promise<import('./payload.types').AIRuntimeCapabilities>;
     aiComplete(payload: import('./payload.types').AICompletePayload): Promise<import('./payload.types').AICompleteResult>;
     piaSearchAnswer(payload: import('./payload.types').PiaSearchAnswerPayload): Promise<import('./payload.types').PiaSearchAnswerResult>;
+    weeklyFocusRank(payload: import('./payload.types').WeeklyFocusRankPayload): Promise<import('./payload.types').WeeklyFocusRankResult>;
     appsDbGetEntries(payload: import('./payload.types').AppsDbGetEntriesPayload): Promise<import('./payload.types').AppsDbEntriesResult>;
     appsDbUpsertEntry(payload: import('./payload.types').AppsDbUpsertEntryPayload): Promise<import('./payload.types').AppsDbEntry>;
     appsDbDeleteEntry(payload: import('./payload.types').AppsDbDeleteEntryPayload): Promise<void>;
@@ -779,6 +823,7 @@ export declare function useApi(options?: ApiOptions): {
         id: import('../main.lib').CanvasRetrieve["id"];
         fields?: string;
         lazy_sections?: boolean;
+        skip_error_toast?: boolean;
     }): Promise<import('../main.lib').CanvasRetrieve>;
     getSectionsByIds(payload: {
         canvas_id: import('../main.lib').CanvasRetrieve["id"];
@@ -791,6 +836,7 @@ export declare function useApi(options?: ApiOptions): {
     }>;
     shareCanvas(payload: {
         id: import('../main.lib').CanvasRetrieve["id"];
+        brand_id?: string;
     }): Promise<import('../main.lib').SharedLink>;
     getCanvasRecommendedFiles(payload: {
         canvas_id: import('../main.lib').CanvasRetrieve["id"];