dexie-cloud-addon 4.3.0 → 4.3.3

package/dist/modern/DexieCloudOptions.d.ts

@@ -29,19 +29,16 @@ export interface DexieCloudOptions {
      * - false: Disable OAuth, always use OTP flow
      *
      * Use `false` for backward compatibility if your custom login UI
-     * doesn't handle the `DXCProviderSelection` interaction type yet.
+     * doesn't handle the `DXCSelect` interaction type yet.
      */
     socialAuth?: boolean;
-    /** Redirect URI for OAuth callback (Capacitor/redirect flows).
-     * For web popups, this is auto-detected from window.location.origin.
-     * Required for:
-     * - Capacitor apps: 'myapp://oauth-callback'
-     * - Full-page redirect flows: 'https://myapp.com/oauth-callback'
+    /** Redirect URI for OAuth callback.
+     * Defaults to window.location.href for web SPAs.
+     *
+     * For Capacitor/native apps, set this to a custom URL scheme:
+     * ```
+     * oauthRedirectUri: 'myapp://'
+     * ```
      */
     oauthRedirectUri?: string;
-    /** Use popup window for OAuth flow.
-     * - true (default for web): Opens OAuth in popup, uses postMessage
-     * - false: Opens OAuth in same window or system browser (Capacitor)
-     */
-    oauthPopup?: boolean;
 }

package/dist/modern/authentication/handleOAuthCallback.d.ts

@@ -1,17 +1,18 @@
-/** Parsed OAuth callback parameters */
+/** Parsed OAuth callback parameters from dxc-auth query parameter */
 export interface OAuthCallbackParams {
     /** The Dexie Cloud authorization code */
     code: string;
     /** The OAuth provider that was used */
     provider: string;
-    /** The state parameter for CSRF validation */
+    /** The state parameter */
     state: string;
 }
 /**
- * Parses OAuth callback parameters from the current URL.
+ * Parses OAuth callback parameters from the dxc-auth query parameter.
  *
- * Use this on your OAuth callback page (for redirect/deep link flows)
- * to extract the authorization code and complete the login.
+ * The dxc-auth parameter contains base64url-encoded JSON with the following structure:
+ * - On success: { "code": "...", "provider": "...", "state": "..." }
+ * - On error: { "error": "...", "provider": "...", "state": "..." }
  *
  * @param url - The URL to parse (defaults to window.location.href)
  * @returns OAuthCallbackParams if valid callback, null otherwise
@@ -30,28 +31,33 @@ export declare function validateOAuthState(receivedState: string): boolean;
  */
 export declare function getStoredOAuthProvider(): string | null;
 /**
- * Cleans up OAuth-related query parameters from the URL.
+ * Cleans up the dxc-auth query parameter from the URL.
  * Call this after successfully handling the callback to clean up the browser URL.
  */
 export declare function cleanupOAuthUrl(): void;
 /**
- * Complete handler for OAuth callback pages.
+ * Complete handler for OAuth callback.
  *
- * Parses the callback URL, validates state, and returns the parameters
+ * Parses the dxc-auth query parameter, validates state, and returns the parameters
  * needed to complete the login flow.
  *
+ * Note: For web SPAs using full page redirect, the dexie-cloud-addon automatically
+ * detects and processes the dxc-auth parameter when db.cloud.configure() is called.
+ * This function is primarily useful for Capacitor/native apps handling deep links.
+ *
  * @param url - The callback URL (defaults to window.location.href)
  * @returns OAuthCallbackParams if valid callback, null otherwise
  * @throws OAuthError on validation failure or if callback contains an error
  *
  * @example
  * ```typescript
- * // On your OAuth callback page:
- * const callback = handleOAuthCallback();
- * if (callback) {
- *   await db.cloud.login({ oauthCode: callback.code, provider: callback.provider });
- *   cleanupOAuthUrl();
- * }
+ * // Capacitor deep link handler:
+ * App.addListener('appUrlOpen', async ({ url }) => {
+ *   const callback = handleOAuthCallback(url);
+ *   if (callback) {
+ *     await db.cloud.login({ oauthCode: callback.code, provider: callback.provider });
+ *   }
+ * });
  * ```
  */
 export declare function handleOAuthCallback(url?: string): OAuthCallbackParams | null;

package/dist/modern/authentication/interactWithUser.d.ts

@@ -30,6 +30,9 @@ export type ProviderSelectionResult = {
 /**
  * Prompts the user to select an authentication method (OAuth provider or OTP).
  *
+ * This function converts OAuth providers and OTP option into generic DXCOption[]
+ * for the DXCSelect interaction, handling icon fetching and style hints.
+ *
  * @param userInteraction - The user interaction BehaviorSubject
  * @param providers - Available OAuth providers
  * @param otpEnabled - Whether OTP is available

package/dist/modern/authentication/oauthLogin.d.ts

@@ -1,37 +1,38 @@
-/** Options for OAuth login */
-export interface OAuthLoginOptions {
+import { OAuthError } from '../errors/OAuthError';
+/** Options for initiating OAuth redirect */
+export interface OAuthRedirectOptions {
     /** The Dexie Cloud database URL */
     databaseUrl: string;
     /** The OAuth provider name */
     provider: string;
-    /** Optional redirect URI for non-popup flows */
+    /** Optional redirect URI override.
+     * Defaults to window.location.href for web apps.
+     * For Capacitor/native apps, use a custom URL scheme like 'myapp://'
+     */
     redirectUri?: string;
-    /** Whether to use popup (default: true) */
-    usePopup?: boolean;
-}
-/** Result from OAuth login */
-export interface OAuthLoginResult {
-    /** The Dexie Cloud authorization code */
-    code: string;
-    /** The provider that was used */
-    provider: string;
-    /** The state parameter */
-    state: string;
 }
 /**
- * Initiates OAuth login flow using a popup window.
+ * Initiates OAuth login via full page redirect.
  *
- * Opens a popup to the OAuth provider, listens for postMessage with the result,
- * and returns the Dexie Cloud authorization code.
+ * The page will navigate to the OAuth provider. After authentication,
+ * the user is redirected back to the app with a `dxc-auth` query parameter
+ * containing base64url-encoded JSON with the authorization code.
  *
- * @param options - OAuth login options
- * @returns Promise resolving to OAuthLoginResult
- * @throws OAuthError on failure
- */
-export declare function oauthLogin(options: OAuthLoginOptions): Promise<OAuthLoginResult>;
-/**
- * Initiates OAuth login via redirect (non-popup flow).
- * The page will navigate to the OAuth provider and redirect back to the app.
- * Use handleOAuthCallback on the callback page to complete the flow.
+ * The dexie-cloud-addon automatically detects and processes this parameter
+ * when db.cloud.configure() is called on page load.
+ *
+ * @param options - OAuth redirect options
+ *
+ * @example
+ * ```typescript
+ * // Initiate OAuth login
+ * startOAuthRedirect({
+ *   databaseUrl: 'https://mydb.dexie.cloud',
+ *   provider: 'google'
+ * });
+ * // Page navigates away, user authenticates, then returns with auth code
+ * ```
  */
-export declare function startOAuthRedirect(options: OAuthLoginOptions): void;
+export declare function startOAuthRedirect(options: OAuthRedirectOptions): void;
+/** Map OAuth error strings to error codes */
+export declare function mapOAuthError(error: string): OAuthError['code'];

package/dist/modern/default-ui/LoginDialog.d.ts

@@ -1,6 +1,31 @@
 import { h } from 'preact';
-import { DXCUserInteraction, DXCProviderSelection } from '../types/DXCUserInteraction';
-/** User interactions that have the standard form-based structure */
-type FormBasedInteraction = Exclude<DXCUserInteraction, DXCProviderSelection>;
-export declare function LoginDialog({ title, type, alerts, fields, submitLabel, cancelLabel, onCancel, onSubmit, }: FormBasedInteraction): h.JSX.Element;
+import { DXCOption } from '../types/DXCUserInteraction';
+import { DXCInputField } from '../types/DXCInputField';
+import { DXCAlert } from '../types/DXCAlert';
+/** Props for LoginDialog - accepts any user interaction */
+interface LoginDialogProps {
+    title: string;
+    alerts: DXCAlert[];
+    fields: {
+        [name: string]: DXCInputField;
+    };
+    options?: DXCOption[];
+    submitLabel?: string;
+    cancelLabel?: string | null;
+    onSubmit: (params: {
+        [paramName: string]: string;
+    }) => void;
+    onCancel: () => void;
+}
+/**
+ * Generic dialog that can render:
+ * - Form fields (text inputs)
+ * - Selectable options (buttons)
+ * - Or both together
+ *
+ * When an option is clicked, calls onSubmit({ [option.name]: option.value }).
+ * This unified approach means the same callback handles both form submission
+ * and option selection.
+ */
+export declare function LoginDialog({ title, alerts, fields, options, submitLabel, cancelLabel, onCancel, onSubmit, }: LoginDialogProps): h.JSX.Element;
 export {};

package/dist/modern/default-ui/OptionButton.d.ts

@@ -0,0 +1,21 @@
+import { h } from 'preact';
+import { DXCOption } from '../types/DXCUserInteraction';
+export interface OptionButtonProps {
+    option: DXCOption;
+    onClick: () => void;
+}
+/**
+ * Generic button component for selectable options.
+ * Displays the option's icon and display name.
+ *
+ * The icon can be:
+ * - Inline SVG (iconSvg) - rendered directly with dangerouslySetInnerHTML
+ * - Image URL (iconUrl) - rendered as an img tag
+ *
+ * Style is determined by the styleHint property for branding purposes.
+ */
+export declare function OptionButton({ option, onClick }: OptionButtonProps): h.JSX.Element;
+/**
+ * Visual divider with "or" text.
+ */
+export declare function Divider(): h.JSX.Element;

package/dist/modern/default-ui/SelectDialog.d.ts

@@ -0,0 +1,10 @@
+import { h } from 'preact';
+import { DXCSelect } from '../types/DXCUserInteraction';
+/**
+ * Dialog component for generic option selection.
+ * Displays available options as buttons.
+ *
+ * This component is UI-agnostic and works with any DXCSelect interaction,
+ * whether for authentication, settings, or other selection purposes.
+ */
+export declare function SelectDialog({ title, alerts, options, cancelLabel, onSelect, onCancel, }: DXCSelect): h.JSX.Element;