@jevelin/bridge 2.53.0

package/dist/esm/packages/teams-js/dts/public/offlineStorage/offlineStorage.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Module to interact with the offline storage capability of the host.
+ * Provides a mail-like pattern with inbox, drafts, outbox, and sent boxes
+ * for managing server-driven dynamic schemas with offline-first data persistence.
+ *
+ * @beta
+ * @module
+ */
+import * as drafts from './drafts';
+import * as inbox from './inbox';
+import * as outbox from './outbox';
+import * as sent from './sent';
+import * as sync from './sync';
+/**
+ * Represents a field definition within a schema
+ *
+ * @beta
+ */
+export interface SchemaField {
+    /** The name of the field */
+    name: string;
+    /** The data type of the field */
+    type: 'text' | 'integer' | 'real' | 'boolean' | 'json' | 'blob_ref';
+    /** Whether this field should be indexed for query performance */
+    indexed?: boolean;
+    /** Whether this field is required */
+    required?: boolean;
+    /** Default value for the field */
+    defaultValue?: string | number | boolean;
+}
+/**
+ * Represents a server-driven schema definition used to create storage tables dynamically
+ *
+ * @beta
+ */
+export interface SchemaDefinition {
+    /** Unique identifier for this schema */
+    schemaId: string;
+    /** Version number of the schema, used for migrations */
+    version: number;
+    /** Human-readable display name for the schema */
+    displayName?: string;
+    /** Field definitions for this schema */
+    fields: SchemaField[];
+}
+/**
+ * Information about a registered schema
+ *
+ * @beta
+ */
+export interface SchemaInfo {
+    /** Unique identifier for this schema */
+    schemaId: string;
+    /** Current version number */
+    version: number;
+    /** Human-readable display name */
+    displayName?: string;
+    /** Number of records across all boxes */
+    recordCount: number;
+}
+/**
+ * Result of a schema migration operation
+ *
+ * @beta
+ */
+export interface MigrationResult {
+    /** Whether the migration completed successfully */
+    success: boolean;
+    /** The previous schema version */
+    previousVersion: number;
+    /** The new schema version */
+    currentVersion: number;
+    /** Fields that were added during migration */
+    addedFields: string[];
+    /** Fields that were deprecated during migration */
+    deprecatedFields: string[];
+}
+/**
+ * Represents a filter condition for querying records
+ *
+ * @beta
+ */
+export interface QueryFilter {
+    /** Field name to filter on */
+    field: string;
+    /** Comparison operator */
+    operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'in';
+    /** Value to compare against */
+    value: string | number | boolean | string[] | number[];
+}
+/**
+ * Options for paginated queries
+ *
+ * @beta
+ */
+export interface QueryOptions {
+    /** Filters to apply */
+    filters?: QueryFilter[];
+    /** Field to sort by */
+    sortBy?: string;
+    /** Sort direction */
+    sortOrder?: 'asc' | 'desc';
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Number of results to skip */
+    offset?: number;
+}
+/**
+ * Paginated result set
+ *
+ * @beta
+ */
+export interface PaginatedResult<T = Record<string, unknown>> {
+    /** The result items */
+    items: T[];
+    /** Total number of matching records */
+    totalCount: number;
+    /** Whether there are more results beyond this page */
+    hasMore: boolean;
+}
+/**
+ * The status of a record in the offline storage system
+ *
+ * @beta
+ */
+export declare enum RecordStatus {
+    /** Record is a local draft, not yet submitted for sync */
+    Draft = "draft",
+    /** Record is queued for sync */
+    Pending = "pending",
+    /** Record is currently being synced */
+    Syncing = "syncing",
+    /** Record has been successfully synced */
+    Synced = "synced",
+    /** Record sync has failed */
+    Failed = "failed"
+}
+/**
+ * The box (category) a record belongs to
+ *
+ * @beta
+ */
+export declare enum RecordBox {
+    /** Server-owned records received from the server */
+    Inbox = "inbox",
+    /** Client-owned records created locally but not yet submitted */
+    Drafts = "drafts",
+    /** Sync-owned records submitted and queued/in-progress for upload */
+    Outbox = "outbox",
+    /** Synchronized copy of successfully uploaded records */
+    Sent = "sent"
+}
+/**
+ * Metadata fields attached to every record in offline storage
+ *
+ * @beta
+ */
+export interface RecordMetadata {
+    /** Client-generated unique identifier */
+    id: string;
+    /** Which box this record belongs to */
+    box: RecordBox;
+    /** Current sync status */
+    status: RecordStatus;
+    /** Optimistic locking version (client-side) */
+    version: number;
+    /** Last known server version */
+    serverVersion?: number;
+    /** Timestamp when the record was created */
+    createdAt: number;
+    /** Timestamp when the record was last updated */
+    updatedAt: number;
+    /** Timestamp when the record was last synced */
+    syncedAt?: number;
+    /** Last sync error message, if any */
+    error?: string;
+}
+/**
+ * A record stored in offline storage, combining metadata with schema-driven data
+ *
+ * @beta
+ */
+export type OfflineRecord<T = Record<string, unknown>> = RecordMetadata & {
+    /** The schema-driven data payload */
+    data: T;
+};
+/**
+ * Registers a new schema definition with the offline storage system.
+ * The host will create the necessary storage structures to hold records of this schema.
+ *
+ * @param schema - The schema definition to register
+ * @returns A promise that resolves when the schema has been registered
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function registerSchema(schema: SchemaDefinition): Promise<void>;
+/**
+ * Checks whether a schema with the given identifier is registered locally
+ *
+ * @param schemaId - The unique identifier of the schema to check
+ * @returns A promise that resolves to `true` if the schema exists, `false` otherwise
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function hasSchema(schemaId: string): Promise<boolean>;
+/**
+ * Lists all schemas currently registered in the offline storage system
+ *
+ * @returns A promise that resolves to an array of schema information objects
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function listSchemas(): Promise<SchemaInfo[]>;
+/**
+ * Migrates an existing schema to a new version.
+ * Added fields will be created, removed fields will be marked deprecated (not dropped).
+ *
+ * @param schema - The updated schema definition with an incremented version number
+ * @returns A promise that resolves to the migration result
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function migrateSchema(schema: SchemaDefinition): Promise<MigrationResult>;
+/**
+ * Removes a schema and all its associated records from offline storage.
+ * This operation is irreversible.
+ *
+ * @param schemaId - The unique identifier of the schema to remove
+ * @returns A promise that resolves when the schema has been removed
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function removeSchema(schemaId: string): Promise<void>;
+/**
+ * Checks if the offlineStorage capability is supported by the host
+ * @returns boolean to represent whether the offlineStorage capability is supported
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ *
+ * @beta
+ */
+export declare function isSupported(): boolean;
+export { drafts, inbox, outbox, sent, sync };

package/dist/esm/packages/teams-js/dts/public/offlineStorage/outbox.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Module for managing sync-owned outbox records in offline storage.
+ * Outbox records are submitted drafts that are queued or in-progress for synchronization to the server.
+ *
+ * @beta
+ * @module
+ */
+import { OfflineRecord, RecordStatus } from './offlineStorage';
+/**
+ * Summary information about the outbox state
+ *
+ * @beta
+ */
+export interface OutboxSummary {
+    /** Total number of records in the outbox */
+    totalCount: number;
+    /** Number of records pending sync */
+    pendingCount: number;
+    /** Number of records currently syncing */
+    syncingCount: number;
+    /** Number of records that failed to sync */
+    failedCount: number;
+}
+/**
+ * An outbox entry with additional sync status information
+ *
+ * @beta
+ */
+export interface OutboxEntry {
+    /** The offline record data */
+    record: OfflineRecord;
+    /** Number of sync retry attempts made */
+    retryCount: number;
+    /** Timestamp of the next scheduled retry, if applicable */
+    nextRetryAt?: number;
+}
+/**
+ * Handler invoked when the status of an outbox record changes
+ *
+ * @beta
+ */
+export type OutboxStatusChangeHandler = (schemaId: string, id: string, status: RecordStatus, error?: string) => void;
+/**
+ * Lists all outbox records for a given schema
+ *
+ * @param schemaId - The schema identifier to list outbox records for
+ * @returns A promise that resolves to an array of outbox entries
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function list(schemaId: string): Promise<OutboxEntry[]>;
+/**
+ * Gets a summary of the outbox state across all schemas or for a specific schema
+ *
+ * @param schemaId - Optional schema identifier to get summary for. If omitted, returns summary across all schemas.
+ * @returns A promise that resolves to an outbox summary
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function getSummary(schemaId?: string): Promise<OutboxSummary>;
+/**
+ * Retries synchronization of a failed outbox record
+ *
+ * @param schemaId - The schema identifier for this record
+ * @param id - The unique identifier of the outbox record to retry
+ * @returns A promise that resolves when the record has been re-queued for sync
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function retry(schemaId: string, id: string): Promise<void>;
+/**
+ * Cancels an outbox record, moving it back to drafts
+ *
+ * @param schemaId - The schema identifier for this record
+ * @param id - The unique identifier of the outbox record to cancel
+ * @returns A promise that resolves when the record has been moved back to drafts
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function cancel(schemaId: string, id: string): Promise<void>;
+/**
+ * Registers a handler to be called when the status of an outbox record changes
+ *
+ * @param handler - The handler function to invoke on status changes
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function registerOnStatusChangeHandler(handler: OutboxStatusChangeHandler): void;
+/**
+ * Checks if the offlineStorage.outbox capability is supported by the host
+ * @returns boolean to represent whether the offlineStorage.outbox capability is supported
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ *
+ * @beta
+ */
+export declare function isSupported(): boolean;

package/dist/esm/packages/teams-js/dts/public/offlineStorage/sent.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Module for managing synchronized copies of successfully uploaded records.
+ * Sent records are confirmation copies that have been synced to the server.
+ *
+ * @beta
+ * @module
+ */
+import { OfflineRecord, PaginatedResult, QueryOptions } from './offlineStorage';
+/**
+ * Retrieves a single sent record by its identifier
+ *
+ * @param schemaId - The schema identifier for this record
+ * @param id - The unique identifier of the sent record to retrieve
+ * @returns A promise that resolves to the sent record
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function get(schemaId: string, id: string): Promise<OfflineRecord>;
+/**
+ * Queries sent records with optional filtering and pagination
+ *
+ * @param schemaId - The schema identifier to query
+ * @param options - Optional query parameters including filters, sorting, and pagination
+ * @returns A promise that resolves to a paginated result set
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function query(schemaId: string, options?: QueryOptions): Promise<PaginatedResult>;
+/**
+ * Lists sent records that were synced after a given timestamp
+ *
+ * @param schemaId - The schema identifier to list sent records for
+ * @param since - Unix timestamp in milliseconds; only records synced after this time will be returned
+ * @returns A promise that resolves to an array of sent records
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function listSince(schemaId: string, since: number): Promise<OfflineRecord[]>;
+/**
+ * Removes sent records older than the specified timestamp to free up storage space
+ *
+ * @param schemaId - The schema identifier to purge records from
+ * @param olderThan - Unix timestamp in milliseconds; records synced before this time will be removed
+ * @returns A promise that resolves to the number of records purged
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function purge(schemaId: string, olderThan: number): Promise<number>;
+/**
+ * Checks if the offlineStorage.sent capability is supported by the host
+ * @returns boolean to represent whether the offlineStorage.sent capability is supported
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ *
+ * @beta
+ */
+export declare function isSupported(): boolean;

package/dist/esm/packages/teams-js/dts/public/offlineStorage/sync.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Module for controlling and monitoring the synchronization engine in offline storage.
+ * The sync module provides APIs to trigger sync operations, monitor status, and handle conflicts.
+ *
+ * @beta
+ * @module
+ */
+/**
+ * Represents the overall synchronization status
+ *
+ * @beta
+ */
+export declare enum SyncState {
+    /** Sync engine is idle, no operations in progress */
+    Idle = "idle",
+    /** Sync engine is actively uploading/downloading records */
+    Syncing = "syncing",
+    /** Sync engine is waiting for network connectivity */
+    WaitingForNetwork = "waitingForNetwork",
+    /** Sync engine encountered an error */
+    Error = "error"
+}
+/**
+ * Detailed sync status information
+ *
+ * @beta
+ */
+export interface SyncStatus {
+    /** Current state of the sync engine */
+    state: SyncState;
+    /** Timestamp of the last successful sync */
+    lastSyncAt?: number;
+    /** Number of records pending upload */
+    pendingUploadCount: number;
+    /** Number of records pending download */
+    pendingDownloadCount: number;
+    /** Whether the device currently has network connectivity */
+    isOnline: boolean;
+    /** Error message if state is Error */
+    error?: string;
+}
+/**
+ * Result of a manually triggered sync operation
+ *
+ * @beta
+ */
+export interface SyncResult {
+    /** Whether the sync operation completed successfully */
+    success: boolean;
+    /** Number of records uploaded to the server */
+    uploadedCount: number;
+    /** Number of records downloaded from the server */
+    downloadedCount: number;
+    /** Number of conflicts encountered during sync */
+    conflictCount: number;
+    /** Timestamp when this sync completed */
+    completedAt: number;
+}
+/**
+ * Strategy for resolving conflicts between client and server versions
+ *
+ * @beta
+ */
+export declare enum ConflictStrategy {
+    /** Server version always wins (default) */
+    ServerWins = "serverWins",
+    /** Client version always wins */
+    ClientWins = "clientWins",
+    /** Escalate to the application layer for manual resolution */
+    Manual = "manual"
+}
+/**
+ * Information about a sync conflict
+ *
+ * @beta
+ */
+export interface ConflictInfo {
+    /** The schema identifier of the conflicting record */
+    schemaId: string;
+    /** The record identifier */
+    recordId: string;
+    /** The client version of the data */
+    clientData: Record<string, unknown>;
+    /** The server version of the data */
+    serverData: Record<string, unknown>;
+    /** Client-side version number */
+    clientVersion: number;
+    /** Server-side version number */
+    serverVersion: number;
+}
+/**
+ * Handler invoked when the sync status changes
+ *
+ * @beta
+ */
+export type SyncStatusChangeHandler = (status: SyncStatus) => void;
+/**
+ * Handler invoked when a sync conflict is detected and the strategy is Manual
+ *
+ * @beta
+ */
+export type SyncConflictHandler = (conflict: ConflictInfo) => void;
+/**
+ * Triggers an immediate synchronization operation
+ *
+ * @returns A promise that resolves to the sync result when the operation completes
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function trigger(): Promise<SyncResult>;
+/**
+ * Gets the current synchronization status
+ *
+ * @returns A promise that resolves to the current sync status
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function getStatus(): Promise<SyncStatus>;
+/**
+ * Sets the conflict resolution strategy for a given schema
+ *
+ * @param schemaId - The schema identifier to configure
+ * @param strategy - The conflict resolution strategy to use
+ * @returns A promise that resolves when the strategy has been set
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function setConflictStrategy(schemaId: string, strategy: ConflictStrategy): Promise<void>;
+/**
+ * Resolves a conflict by choosing either the client or server version
+ *
+ * @param schemaId - The schema identifier of the conflicting record
+ * @param recordId - The record identifier
+ * @param resolution - Whether to keep the client or server version
+ * @returns A promise that resolves when the conflict has been resolved
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function resolveConflict(schemaId: string, recordId: string, resolution: 'client' | 'server'): Promise<void>;
+/**
+ * Registers a handler to be called when the sync status changes
+ *
+ * @param handler - The handler function to invoke on status changes
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function registerOnStatusChangeHandler(handler: SyncStatusChangeHandler): void;
+/**
+ * Registers a handler to be called when a sync conflict is detected.
+ * This handler is only invoked when the conflict strategy is set to {@link ConflictStrategy.Manual}.
+ *
+ * @param handler - The handler function to invoke when a conflict occurs
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ * @throws Error if the offlineStorage capability is not supported
+ *
+ * @beta
+ */
+export declare function registerOnConflictHandler(handler: SyncConflictHandler): void;
+/**
+ * Checks if the offlineStorage.sync capability is supported by the host
+ * @returns boolean to represent whether the offlineStorage.sync capability is supported
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ *
+ * @beta
+ */
+export declare function isSupported(): boolean;

package/dist/esm/packages/teams-js/dts/public/pages/appButton.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Provides APIs to interact with the app button part of the SDK.
+ * @module
+ */
+import { handlerFunctionType } from './pages';
+/**
+ * Registers a handler for clicking the app button.
+ * Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
+ * @param handler - The handler to invoke when the personal app button is clicked in the app bar.
+ */
+export declare function onClick(handler: handlerFunctionType): void;
+/**
+ * Registers a handler for entering hover of the app button.
+ * Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
+ * @param handler - The handler to invoke when entering hover of the personal app button in the app bar.
+ */
+export declare function onHoverEnter(handler: handlerFunctionType): void;
+/**
+ * Registers a handler for exiting hover of the app button.
+ * Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
+ * @param handler - The handler to invoke when exiting hover of the personal app button in the app bar.
+ */
+export declare function onHoverLeave(handler: handlerFunctionType): void;
+/**
+ * Checks if pages.appButton capability is supported by the host
+ * @returns boolean to represent whether the pages.appButton capability is supported
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ */
+export declare function isSupported(): boolean;

package/dist/esm/packages/teams-js/dts/public/pages/backStack.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Provides APIs for handling the user's navigational history.
+ * @module
+ */
+import { backButtonHandlerFunctionType } from './pages';
+/**
+ * @hidden
+ * Register backButtonPress handler.
+ *
+ * @internal
+ * Limited to Microsoft-internal use.
+ */
+export declare function _initialize(): void;
+/**
+ * Navigates back in the hosted application. See {@link pages.backStack.registerBackButtonHandler} for notes on usage.
+ * @returns Promise that resolves when the navigation has completed.
+ */
+export declare function navigateBack(): Promise<void>;
+/**
+ * Registers a handler for user presses of the host client's back button. Experiences that maintain an internal
+ * navigation stack should use this handler to navigate the user back within their frame. If an application finds
+ * that after running its back button handler it cannot handle the event it should call the navigateBack
+ * method to ask the host client to handle it instead.
+ * @param handler - The handler to invoke when the user presses the host client's back button.
+ */
+export declare function registerBackButtonHandler(handler: backButtonHandlerFunctionType): void;
+/**
+ * @hidden
+ * Undocumented helper function with shared code between deprecated version and current version of the registerBackButtonHandler API.
+ *
+ * @internal
+ * Limited to Microsoft-internal use
+ * @param apiVersionTag - The tag indicating API version number with name
+ * @param handler - The handler to invoke when the user presses the host client's back button.
+ * @param versionSpecificHelper - The helper function containing logic pertaining to a specific version of the API.
+ */
+export declare function registerBackButtonHandlerHelper(apiVersionTag: string, handler: () => boolean, versionSpecificHelper?: () => void): void;
+/**
+ * Checks if the pages.backStack capability is supported by the host
+ * @returns boolean to represent whether the pages.backStack capability is supported
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ */
+export declare function isSupported(): boolean;