@salesforce/platform-sdk 3.0.0

package/dist/core/view.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * Theme mode
+ */
+export type ThemeMode = "light" | "dark";
+/**
+ * Theme object
+ */
+export interface Theme {
+    mode: ThemeMode;
+}
+/**
+ * Message severity level for alerts and toasts
+ *
+ * Determines the visual styling and importance of notifications:
+ * - `info` - Informational messages (blue/neutral)
+ * - `success` - Successful operations (green)
+ * - `warning` - Warning messages requiring attention (yellow/orange)
+ * - `error` - Error messages for failed operations (red)
+ */
+export type MessageLevel = "info" | "success" | "warning" | "error";
+/**
+ * Configuration options for displaying alerts
+ *
+ * Alerts are modal notifications that typically require user acknowledgment.
+ * They block interaction until dismissed and are used for important messages.
+ */
+export interface AlertOptions {
+    /**
+     * The message content to display in the alert
+     */
+    message: string;
+    /**
+     * The severity level of the alert
+     *
+     * Determines the visual styling and icon. Defaults to "info" if not specified.
+     */
+    level?: MessageLevel;
+}
+/**
+ * Configuration options for displaying toast notifications
+ *
+ * Toasts are non-blocking, temporary notifications that automatically dismiss
+ * after a short duration. They're ideal for status updates and confirmations.
+ */
+export interface ToastOptions {
+    /**
+     * The message content to display in the toast
+     */
+    message: string;
+    /**
+     * The severity level of the toast
+     *
+     * Determines the visual styling and icon. Defaults to "info" if not specified.
+     */
+    level?: MessageLevel;
+}
+/**
+ * Configuration options for displaying modal dialogs
+ *
+ * Modals allow custom HTML content to be displayed in an overlay dialog.
+ * The template is loaded from a UI resource and can receive parameters.
+ */
+export interface ModalOptions {
+    /**
+     * URI of the HTML template to load in the modal
+     *
+     * Format: "ui://widget/[name].html"
+     * The template file should be included in your application's UI resources.
+     *
+     * @example "ui://widget/confirmation.html"
+     * @example "ui://widget/settings.html"
+     */
+    componentReference: string;
+    /**
+     * Parameters to pass to the modal template
+     *
+     * These parameters are accessible within the modal via the host's API.
+     * For example, in OpenAI surface: `window.openai.view.params`
+     *
+     * @example { userId: "123", mode: "edit" }
+     */
+    params?: Record<string, unknown>;
+}
+/**
+ * ViewSDK API - Provides methods for displaying UI elements and managing view state
+ *
+ * This SDK enables UI Bundles to interact with the host's UI layer by displaying
+ * alerts, toast notifications, modal dialogs, and managing application state. All methods
+ * are optional and may not be available depending on the runtime surface.
+ *
+ * @example
+ * ```typescript
+ * const viewSDK = await createViewSDK();
+ *
+ * // Display a success toast
+ * await viewSDK.displayToast?.({
+ *   message: 'Operation completed successfully',
+ *   level: 'success'
+ * });
+ *
+ * // Mark application as having unsaved changes
+ * await viewSDK.markDirtyState?.();
+ * ```
+ */
+export interface ViewSDK {
+    /**
+     * Display an alert message in the host environment
+     *
+     * Alerts are typically modal and require user acknowledgment before dismissing.
+     * Use alerts for important messages that require immediate attention.
+     *
+     * @param options - Alert configuration options
+     * @returns Promise that resolves when the alert is displayed
+     *
+     * @example
+     * ```typescript
+     * await viewSDK.displayAlert?.({
+     *   message: 'Please save your work before continuing',
+     *   level: 'warning'
+     * });
+     * ```
+     */
+    displayAlert?(options: AlertOptions): Promise<void>;
+    /**
+     * Display a toast notification in the host environment
+     *
+     * Toasts are non-blocking, temporary notifications that auto-dismiss.
+     * Use toasts for success confirmations, status updates, or informational messages
+     * that don't require user interaction.
+     *
+     * @param options - Toast configuration options
+     * @returns Promise that resolves when the toast is displayed
+     *
+     * @example
+     * ```typescript
+     * await viewSDK.displayToast?.({
+     *   message: 'File uploaded successfully',
+     *   level: 'success'
+     * });
+     * ```
+     */
+    displayToast?(options: ToastOptions): Promise<void>;
+    /**
+     * Display a modal dialog with custom UI in the host environment
+     *
+     * Modals allow you to display custom HTML content in a dialog overlay.
+     * The template is loaded from a UI resource URI, and parameters can be
+     * passed to the modal for dynamic content.
+     *
+     * @param options - Modal configuration options
+     * @returns Promise that resolves when the modal is displayed
+     *
+     * @example
+     * ```typescript
+     * await viewSDK.displayModal?.({
+     *   template: 'ui://widget/settings.html',
+     *   params: {
+     *     theme: 'dark',
+     *     apiKey: 'abc123'
+     *   }
+     * });
+     * ```
+     */
+    displayModal?(options: ModalOptions): Promise<void>;
+    /**
+     * Navigate to a different URL within the application
+     *
+     * This method triggers navigation in the host environment. The behavior may vary
+     * depending on the surface (e.g., full page navigation, iframe navigation, etc.).
+     *
+     * @param url - The URL to navigate to (can be relative or absolute)
+     * @returns Promise that resolves when navigation is initiated
+     *
+     * @example
+     * ```typescript
+     * await viewSDK.navigateTo?.('/dashboard');
+     * await viewSDK.navigateTo?.('https://example.com/page');
+     * ```
+     */
+    navigateTo?(url: string): Promise<void>;
+    /**
+     * Mark the application state as "dirty" (having unsaved changes)
+     *
+     * This notifies the host that the application has unsaved changes. The host may
+     * display a visual indicator (e.g., asterisk in title) and prompt the user before
+     * navigating away or closing the application.
+     *
+     * @returns Promise that resolves when the dirty state is marked
+     *
+     * @example
+     * ```typescript
+     * // User made changes to a form
+     * formInput.addEventListener('input', async () => {
+     *   await viewSDK.markDirtyState?.();
+     * });
+     * ```
+     */
+    markDirtyState?(): Promise<void>;
+    /**
+     * Clear the application's "dirty" state (no unsaved changes)
+     *
+     * This notifies the host that all changes have been saved. Should be called
+     * after successfully persisting data to remove unsaved change indicators.
+     *
+     * @returns Promise that resolves when the dirty state is cleared
+     *
+     * @example
+     * ```typescript
+     * // After successfully saving data
+     * async function saveForm(data) {
+     *   await api.save(data);
+     *   await viewSDK.clearDirtyState?.();
+     * }
+     * ```
+     */
+    clearDirtyState?(): Promise<void>;
+    /**
+     * Dispatch a custom event to the host environment
+     *
+     * This allows the application to send custom events with associated data to the
+     * host. The host can listen for these events and respond accordingly.
+     *
+     * @param event - The event name/type to dispatch
+     * @param data - Associated event data as key-value pairs
+     * @returns Promise that resolves when the event is dispatched
+     *
+     * @example
+     * ```typescript
+     * await viewSDK.dispatchEvent?.('user-action', {
+     *   action: 'click',
+     *   buttonId: 'submit',
+     *   timestamp: Date.now()
+     * });
+     * ```
+     */
+    dispatchEvent?(event: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Get UI properties from the host and subscribe to changes
+     *
+     * Returns an object containing a promise for the initial props and a subscribe
+     * function to listen for prop updates. UI props allow the host to configure
+     * the application's appearance or behavior dynamically.
+     *
+     * @returns Object with props promise and subscribe function
+     *
+     * @example
+     * ```typescript
+     * const uiProps = viewSDK.getUiProps?.();
+     *
+     * // Get initial props
+     * const initialProps = await uiProps.props;
+     * console.log('Theme:', initialProps.theme);
+     *
+     * // Subscribe to prop changes
+     * uiProps.subscribe((newProps) => {
+     *   console.log('Props updated:', newProps);
+     *   // Update UI based on new props
+     * });
+     * ```
+     */
+    getUiProps?(): {
+        props: Promise<Record<string, unknown>>;
+        subscribe: (callback: (props: Record<string, unknown>) => void) => void;
+    };
+    /**
+     * Resize the application viewport
+     *
+     * Requests the host to resize the application container to the specified dimensions.
+     * Useful for adaptive layouts or when content size changes dynamically.
+     *
+     * @param width - The desired width (e.g., "500px", "100%", "auto")
+     * @param height - The desired height (e.g., "300px", "100%", "auto")
+     * @returns Promise that resolves when resize is complete
+     *
+     * @example
+     * ```typescript
+     * // Resize to specific pixel dimensions
+     * await viewSDK.resize?.('800px', '600px');
+     *
+     * // Auto-resize based on content
+     * await viewSDK.resize?.('auto', 'auto');
+     * ```
+     */
+    resize?(width: string, height: string): Promise<void>;
+    /**
+     * Get the current theme from the host environment
+     *
+     * Returns the current theme (light/dark mode) as reported by the host.
+     * Returns null if the host has not provided theme information.
+     *
+     * @returns The current theme or null if not available
+     *
+     * @example
+     * ```typescript
+     * const theme = viewSDK.getTheme?.();
+     * if (theme) {
+     *   document.body.classList.toggle('dark', theme.mode === 'dark');
+     * }
+     * ```
+     */
+    getTheme?(): Theme | null;
+}
+//# sourceMappingURL=view.d.ts.map

package/dist/core/view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../src/core/view.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,KAAK;IACrB,IAAI,EAAE,SAAS,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;;;;;OAQG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,OAAO;IACvB;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjC;;;;;;;;;;;;;;;;OAgBG;IACH,eAAe,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAElC;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5E;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,UAAU,CAAC,IAAI;QACd,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QACxC,SAAS,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,KAAK,IAAI,CAAC;KACxE,CAAC;IAEF;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtD;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,IAAI,KAAK,GAAG,IAAI,CAAC;CAC1B"}

package/dist/data/gql.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+export declare function gql(strings: TemplateStringsArray, ...values: unknown[]): string;
+//# sourceMappingURL=gql.d.ts.map

package/dist/data/gql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gql.d.ts","sourceRoot":"","sources":["../../src/data/gql.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wBAAgB,GAAG,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAS/E"}

package/dist/data/index.d.ts

@@ -0,0 +1,34 @@
+import { DataSDK, SDKOptions } from '../core';
+import { MosaicDataSDKOptions } from './mosaic';
+export type StatusCallback = () => Promise<unknown> | void;
+/**
+ * Options for creating a WebAppDataSDK
+ */
+export interface WebAppDataSDKOptions {
+    basePath?: string;
+    onStatus?: Partial<Record<number, StatusCallback>>;
+}
+export type { MosaicDataSDKOptions };
+/**
+ * Options for creating a DataSDK instance.
+ */
+export interface DataSDKOptions extends SDKOptions {
+    webapp?: WebAppDataSDKOptions;
+    mosaic?: MosaicDataSDKOptions;
+}
+/**
+ * Create and initialize a DataSDK instance based on the detected surface.
+ * Each call creates a new instance; options are applied to every call.
+ *
+ * @param options - Optional configuration including surface override and web app options
+ * @returns Promise resolving to an initialized DataSDK instance
+ */
+export declare function createDataSDK(options?: DataSDKOptions): Promise<DataSDK>;
+export { gql } from './gql';
+export type { DataSDK, GraphQLRequest, GraphQLResponse, SDKOptions } from '../core';
+export type NodeOfConnection<T> = T extends {
+    edges?: (infer E)[] | null;
+} | null ? E extends {
+    node?: infer N;
+} | null ? N : never : never;
+//# sourceMappingURL=index.d.ts.map

package/dist/data/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/data/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAiB,KAAK,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAIpE,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;CACnD;AAED,YAAY,EAAE,oBAAoB,EAAE,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,UAAU;IACjD,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAqBxE;AAED,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEpF,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS;IAC3C,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC;CAC3B,GAAG,IAAI,GACL,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,GAClC,CAAC,GACD,KAAK,GACN,KAAK,CAAC"}

package/dist/data/mosaic/fetch.d.ts

@@ -0,0 +1,21 @@
+import { FetchService, RequestInterceptor } from '@conduit-client/service-fetch-network/v1';
+/**
+ * Creates a request interceptor that prepends a base URL to relative string URLs.
+ *
+ * @param baseUrl - The base URL to prepend (e.g. "https://myorg.salesforce.com")
+ */
+export declare function createBaseUrlInterceptor(baseUrl: string): RequestInterceptor;
+/**
+ * Creates a request interceptor that adds an Authorization Bearer header.
+ *
+ * @param accessToken - The access token to use for authentication
+ */
+export declare function createAuthInterceptor(accessToken: string): RequestInterceptor;
+/**
+ * Creates a fetch service configured with optional base URL and auth interceptors.
+ *
+ * @param baseUrl - Optional base URL for resolving relative paths
+ * @param accessToken - Optional access token for Bearer authentication
+ */
+export declare function createMosaicFetchService(baseUrl?: string, accessToken?: string): FetchService;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/data/mosaic/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../../src/data/mosaic/fetch.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAIN,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,MAAM,0CAA0C,CAAC;AAGlD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAS5E;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,CAI7E;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,YAAY,CAY7F"}

package/dist/data/mosaic/index.d.ts

@@ -0,0 +1,22 @@
+import { DataSDK, GraphQLRequest, GraphQLResponse } from '../../core';
+/**
+ * Options for creating a MosaicDataSDK
+ */
+export interface MosaicDataSDKOptions {
+    instanceUrl?: string;
+    accessToken?: string;
+    apiVersion?: string;
+}
+/**
+ * Data SDK implementation for the Mosaic surface (Node.js / server-side).
+ *
+ * Uses the conduit-client fetch service without CSRF protection or session handling.
+ * Authentication is handled via an access token provided through options or MOSAIC_ENV.
+ */
+export declare class MosaicDataSDK implements DataSDK {
+    private readonly clientFetch;
+    private readonly pathData;
+    constructor(options?: MosaicDataSDKOptions);
+    graphql<T, V>({ query, variables, operationName, }: GraphQLRequest<V>): Promise<GraphQLResponse<T>>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/data/mosaic/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/data/mosaic/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG3E;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,OAAO;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAe;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,OAAO,CAAC,EAAE,oBAAoB;IAWpC,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,EACnB,KAAK,EACL,SAAS,EACT,aAAa,GACb,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;CAYlD"}

package/dist/data/openai/index.d.ts

@@ -0,0 +1,9 @@
+import { DataSDK, GraphQLRequest, GraphQLResponse } from '../../core';
+/**
+ * Data SDK implementation for the OpenAI surface, which delegates GraphQL
+ * queries to the Salesforce MCP server via the ChatGPT bridge.
+ */
+export declare class OpenAIDataSDK implements DataSDK {
+    graphql<T, V>({ query, variables, operationName, }: GraphQLRequest<V>): Promise<GraphQLResponse<T>>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/data/openai/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/data/openai/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAI3E;;;GAGG;AACH,qBAAa,aAAc,YAAW,OAAO;IACtC,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,EACnB,KAAK,EACL,SAAS,EACT,aAAa,GACb,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;CASlD"}

package/dist/data/shared/graphql/cache/command.d.ts

@@ -0,0 +1,93 @@
+import { HttpCacheControlCommand } from '@conduit-client/command-http-cache-control/v1';
+import { GraphQLResponse } from '@conduit-client/onestore-graphql-parser/v1';
+import { Cache, ReadonlyCache } from '@conduit-client/service-cache/v1';
+import { CacheControlStrategyConfig, NamedCacheControllerService } from '@conduit-client/service-cache-control/v1';
+import { FetchService, NamedFetchService } from '@conduit-client/service-fetch-network/v1';
+import { NamedPubSubService } from '@conduit-client/service-pubsub/v1';
+import { Result, SyncOrAsync } from '@conduit-client/utils';
+export interface GraphQLResourceRequestParams {
+    query: string;
+    variables?: Record<string, unknown>;
+    operationName?: string;
+}
+type Services = NamedCacheControllerService & Partial<NamedPubSubService> & NamedFetchService;
+/**
+ * Per-resource HTTP GraphQL cache-control command.
+ *
+ * Caches the `data` portion of a GraphQL response keyed by `{query, variables,
+ * operationName}` for {@link DEFAULT_MAX_AGE_SECONDS} seconds. The query is keyed by
+ * its raw string; semantically identical queries with different formatting produce
+ * different cache entries. Callers that want whitespace-equivalent deduplication
+ * should normalize at the call site. Mirrors OneStore's
+ * `HttpCacheControlCommand` lifecycle (read → fetch → write → re-read) and is intended as
+ * a building block for higher-level cache integrations rather than a standalone end-user
+ * API.
+ *
+ * ## Caching policy
+ *
+ * - Successful responses with a non-empty `data` object are cached.
+ * - Responses where `data` is `null`, missing, or `{}` are NOT cached. An empty `data`
+ *   object usually indicates a transient server condition; caching it would poison the
+ *   cache for the full TTL.
+ * - Responses with a non-empty `errors` array are surfaced as a `UserVisibleError` and
+ *   are NOT cached. Partial-data preservation (responses carrying both `data` and
+ *   `errors`) is not implemented at this layer; callers requiring it should use a
+ *   higher-level command that overrides `handleCacheControllerResult` (see OneStore's
+ *   `HttpGraphQLNormalizedCacheControlCommand`).
+ * - Mutations and subscriptions ARE cached at this layer because operation kind is not
+ *   inspected. Higher-level integrations that route mutations through this command MUST
+ *   bypass it for non-query operations to avoid silent re-issue of cached mutation
+ *   responses.
+ *
+ * ## Stale-while-revalidate
+ *
+ * After the `max-age` window elapses, the next call to `execute()` will:
+ *
+ * 1. Return the previously-cached (stale) value as the immediate result.
+ * 2. Fire a network request in the background.
+ * 3. Publish the fresh value to PubSub subscribers via `cacheUpdate`.
+ *
+ * Non-subscribed callers therefore observe one cycle of stale data after expiry and
+ * will only receive the refreshed value on a subsequent `execute()` or `refresh()` call.
+ * Callers that need synchronous freshness should subscribe via the returned
+ * `SubscribableResult` or call `refresh()` explicitly.
+ *
+ * ## Variable handling
+ *
+ * Variables are deep-cloned via `JSON.parse(JSON.stringify(...))` at construction time
+ * so that subsequent mutation of the caller's object does not desync the cache key from
+ * the request body. Values that throw inside `JSON.stringify` (circular references,
+ * BigInt) are rejected at construction with a typed error carrying the operation name.
+ * Values that silently lose information through the round-trip (`Map`, `Symbol`,
+ * `function`) are not detected — those would also produce an invalid GraphQL request
+ * body on the wire path independent of the cache.
+ */
+export declare class HttpGraphQLResourceCacheControlCommand<TData extends Record<string, unknown> = Record<string, unknown>> extends HttpCacheControlCommand<TData, object, GraphQLResponse<TData>> {
+    private readonly url;
+    private readonly query;
+    private readonly normalizedVariables;
+    private readonly normalizedOperationName;
+    constructor(config: GraphQLResourceRequestParams, services: Services, url: string);
+    protected get fetchParams(): Parameters<FetchService>;
+    buildKey(): string;
+    /**
+     * Reads from the cache and returns the cache result or error
+     *
+     * In case of a missing or partial result, this should return either a DataNotFoundError or
+     * DataIncompleteError, respectively, in the Error response
+     *
+     * Note that any subclass should JUST try to read the data from the cache here; it should
+     * NOT try to take metadata (eg cache control semantics) into account while reading the
+     * data. The CacheController is responsible for enforcing those semantics.
+     *
+     * @param cache source of cached data
+     * @returns result or error from the cache
+     */
+    readFromCache(cache: ReadonlyCache): SyncOrAsync<Result<TData, Error>>;
+    writeToCache(cache: Cache, networkResult: Result<GraphQLResponse<TData>, Error>): SyncOrAsync<void>;
+    protected get cacheControlStrategyConfig(): CacheControlStrategyConfig;
+    protected responseHasErrors(data: GraphQLResponse<TData>): boolean | undefined;
+    protected processFetchReturnValue(json: GraphQLResponse<TData>): Result<GraphQLResponse<TData>, Error>;
+}
+export {};
+//# sourceMappingURL=command.d.ts.map

package/dist/data/shared/graphql/cache/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../../src/data/shared/graphql/cache/command.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,+CAA+C,CAAC;AACxF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAClF,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAC7E,OAAO,KAAK,EACX,0BAA0B,EAC1B,2BAA2B,EAC3B,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAC;AAChG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,EAON,KAAK,MAAM,EACX,KAAK,WAAW,EAChB,MAAM,uBAAuB,CAAC;AAsB/B,MAAM,WAAW,4BAA4B;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,KAAK,QAAQ,GAAG,2BAA2B,GAAG,OAAO,CAAC,kBAAkB,CAAC,GAAG,iBAAiB,CAAC;AAE9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,qBAAa,sCAAsC,CAClD,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAC9D,SAAQ,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;IAQtE,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA0B;IAC9D,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAS;gBAGhD,MAAM,EAAE,4BAA4B,EACpC,QAAQ,EAAE,QAAQ,EACD,GAAG,EAAE,MAAM;IAW7B,SAAS,KAAK,WAAW,IAAI,UAAU,CAAC,YAAY,CAAC,CAapD;IAED,QAAQ,IAAI,MAAM;IAQlB;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAStE,YAAY,CACX,KAAK,EAAE,KAAK,EACZ,aAAa,EAAE,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,GAClD,WAAW,CAAC,IAAI,CAAC;IAqBpB,SAAS,KAAK,0BAA0B,IAAI,0BAA0B,CAMrE;IAED,SAAS,CAAC,iBAAiB,CAAC,IAAI,EAAE,eAAe,CAAC,KAAK,CAAC;cAIrC,uBAAuB,CACzC,IAAI,EAAE,eAAe,CAAC,KAAK,CAAC,GAC1B,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CAMxC"}

package/dist/data/shared/graphql/cache/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/data/shared/graphql/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/data/shared/graphql/cache/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,EAAE,CAAC"}

package/dist/data/shared/graphql/headers.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * Builds the canonical request header set for Salesforce GraphQL calls.
+ * Used by both the WebApp DataSDK transport path and the cache control
+ * command, so the wire format stays identical regardless of which path
+ * a consumer's request takes.
+ */
+export declare function buildGraphQLRequestHeaders(): Record<string, string>;
+//# sourceMappingURL=headers.d.ts.map

package/dist/data/shared/graphql/headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../../../../src/data/shared/graphql/headers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMnE"}

package/dist/data/shared/url-utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+export declare const API_VERSION: string;
+/** Builds the Salesforce data API path for the given version (defaults to {@link API_VERSION}). */
+export declare function buildPathData(version?: string): string;
+//# sourceMappingURL=url-utils.d.ts.map

package/dist/data/shared/url-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-utils.d.ts","sourceRoot":"","sources":["../../../src/data/shared/url-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,WAAW,QAA0E,CAAC;AAEnG,mGAAmG;AACnG,wBAAgB,aAAa,CAAC,OAAO,GAAE,MAAoB,GAAG,MAAM,CAEnE"}

package/dist/data/webapp/client-headers.interceptor.d.ts

@@ -0,0 +1,12 @@
+import { RequestInterceptor } from '@conduit-client/service-fetch-network/v1';
+export declare const CLIENT_NAME_HEADER = "X-SFDC-Client-Name";
+export declare const CLIENT_VERSION_HEADER = "X-SFDC-Client-Version";
+/**
+ * A request interceptor that stamps every outgoing request with SDK identity headers.
+ *
+ * Added headers:
+ *   X-SFDC-Client-Name: the SDK package name
+ *   X-SFDC-Client-Version: the SDK version
+ */
+export declare const clientHeadersInterceptor: RequestInterceptor;
+//# sourceMappingURL=client-headers.interceptor.d.ts.map

package/dist/data/webapp/client-headers.interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-headers.interceptor.d.ts","sourceRoot":"","sources":["../../../src/data/webapp/client-headers.interceptor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAGN,KAAK,kBAAkB,EACvB,MAAM,0CAA0C,CAAC;AAGlD,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AACvD,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAK7D;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,EAAE,kBAItC,CAAC"}

package/dist/data/webapp/csrf/header.interceptor.d.ts

@@ -0,0 +1,19 @@
+import { RequestInterceptor } from '@conduit-client/service-fetch-network/v1';
+import { CsrfTokenManager } from './token-manager';
+export interface HeaderInterceptorConfig {
+    /** URLs that require CSRF tokens on mutating methods (POST, PUT, PATCH, DELETE). */
+    protectedUrls?: string[];
+    /**
+     * URLs that require CSRF tokens on all methods including GET.
+     * Use for endpoints that are sensitive regardless of HTTP method (e.g. Apex REST).
+     */
+    alwaysProtectedUrls?: string[];
+}
+/**
+ * Builds a configured interceptor for applying CSRF header to requests
+ *
+ * @param csrfTokenManager
+ * @param config
+ */
+export declare function buildInterceptor(csrfTokenManager: CsrfTokenManager, config?: HeaderInterceptorConfig): RequestInterceptor;
+//# sourceMappingURL=header.interceptor.d.ts.map

package/dist/data/webapp/csrf/header.interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header.interceptor.d.ts","sourceRoot":"","sources":["../../../../src/data/webapp/csrf/header.interceptor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAGN,KAAK,kBAAkB,EACvB,MAAM,0CAA0C,CAAC;AAElD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAIxD,MAAM,WAAW,uBAAuB;IACvC,oFAAoF;IACpF,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC/B,gBAAgB,EAAE,gBAAgB,EAClC,MAAM,GAAE,uBAA4B,GAClC,kBAAkB,CAkBpB"}

package/dist/data/webapp/csrf/retry.interceptor.d.ts

@@ -0,0 +1,8 @@
+import { FetchParameters } from '@conduit-client/service-fetch-network/v1';
+import { RetryService } from '@conduit-client/service-retry/v1';
+import { HeaderInterceptorConfig } from './header.interceptor';
+import { CsrfTokenManager } from './token-manager';
+export interface RetryInterceptorConfig extends HeaderInterceptorConfig {
+}
+export declare function buildInterceptor(csrfTokenManager: CsrfTokenManager, config?: RetryInterceptorConfig): (fetchArgs: FetchParameters, retryService?: RetryService<Response>) => Promise<Response>;
+//# sourceMappingURL=retry.interceptor.d.ts.map

package/dist/data/webapp/csrf/retry.interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.interceptor.d.ts","sourceRoot":"","sources":["../../../../src/data/webapp/csrf/retry.interceptor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAC;AAChF,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAErE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGxD,MAAM,WAAW,sBAAuB,SAAQ,uBAAuB;CAAG;AAE1E,wBAAgB,gBAAgB,CAC/B,gBAAgB,EAAE,gBAAgB,EAClC,MAAM,GAAE,sBAA2B,IAc3B,WAAW,eAAe,EAAE,eAAe,YAAY,CAAC,QAAQ,CAAC,uBAWzE"}