@locale-labs/miniapp-sdk 0.1.0 → 0.1.2

package/dist/sdk.d.ts

@@ -0,0 +1,161 @@
+import { KernelResponse, UserPayload, LocationPayload, AuthTokenPayload, AlertButton, LocationPickerOptions, AlertPayload, ScrollDirectionPayload, AuthLoginPayload, UrlUpdatePayload } from "@locale-labs/protocol";
+export type { UserPayload, LocationPayload, AuthTokenPayload, LocationPickerOptions, AlertPayload, ScrollDirectionPayload, AuthLoginPayload, UrlUpdatePayload, KernelResponse };
+export type { AlertButton };
+export interface AlertButtonWithAction extends AlertButton {
+    onPress?: () => void;
+}
+/**
+ * Localé Mini-App SDK
+ *
+ * Provides a bridge for Mini-Apps running in sandboxed iframes
+ * to communicate with the Localé Kernel via postMessage protocol.
+ *
+ * @example
+ * ```javascript
+ * const app = new LocaleApp();
+ * const { user, location, token } = await app.init();
+ * app.enableAutoScrollSync();
+ * ```
+ */
+export interface AlertButtonWithAction extends AlertButton {
+    onPress?: () => void;
+}
+export type PickLocationOptions = LocationPickerOptions;
+export interface InitResult {
+    user: UserPayload | null;
+    location: LocationPayload | null;
+    token: string | null;
+}
+export interface LocaleAppConfig {
+    /**
+     * The origin of the Kernel (parent window).
+     * Used for security validation of postMessage.
+     * Defaults to '*' in development, but should be set in production.
+     */
+    kernelOrigin?: string;
+}
+interface SupabaseClient {
+    auth: {
+        setSession: (params: {
+            access_token: string;
+            refresh_token: string;
+        }) => Promise<{
+            error: Error | null;
+        }>;
+    };
+}
+export declare class LocaleApp {
+    private requestId;
+    private requests;
+    private kernelOrigin;
+    private _lastScrollY;
+    private _lastReportedDirection;
+    private _scrollListener;
+    private debugEnabled;
+    constructor(config?: LocaleAppConfig);
+    /**
+     * Logs a message if debug mode is enabled
+     */
+    private _log;
+    /**
+     * Internal method to send messages to the Kernel
+     * @param type - Message type identifier
+     * @param payload - Data to send with the message
+     * @returns Promise that resolves with the Kernel's response
+     */
+    private _send;
+    /**
+     * Initializes the SDK and fetches all necessary context in parallel.
+     * This is the recommended way to start your Mini-App.
+     *
+     * @returns Promise with user, location, and auth token
+     */
+    init(): Promise<InitResult>;
+    /**
+     * Automatically handles scroll detection to hide/show the Kernel's header.
+     * Call this once when your app starts if you want this behavior.
+     *
+     * @param threshold - Minimum scroll pixels before triggering (default: 50)
+     * @param delta - Minimum scroll change before triggering (default: 10)
+     */
+    enableAutoScrollSync(threshold?: number, delta?: number): void;
+    /**
+     * Get the current authenticated user info (public profile)
+     * @returns Promise with user data including id, email, place_id, etc.
+     */
+    getUser(): Promise<unknown>;
+    /**
+     * Get a signed JWT token asserting the user's identity.
+     * This token can be used to authenticate with the Mini App's backend.
+     * @returns Promise with { token: string }
+     */
+    getAuthToken(): Promise<{
+        token: string;
+    }>;
+    /**
+     * Automatically connects the Supabase Client with the current Localé User
+     * using the signed Auth Token.
+     * @param supabaseClient - The Supabase Client instance
+     * @returns Promise with { token: string }
+     */
+    connectSupabase(supabaseClient: SupabaseClient): Promise<{
+        token: string;
+    }>;
+    /**
+     * Get the current user's location context from Localé
+     * @returns Promise with location data (city, coords, etc.)
+     */
+    getLocation(): Promise<unknown>;
+    /**
+     * Show a native alert/modal via the Kernel (similar to React Native Alert)
+     * @param title - Modal title
+     * @param message - Optional message
+     * @param buttons - Array of buttons (if empty, shows "OK")
+     * @param options - Alert options (cancelable, onDismiss)
+     */
+    alert(title: string, message?: string, buttons?: AlertButtonWithAction[], options?: {
+        cancelable?: boolean;
+        onDismiss?: () => void;
+    }): Promise<void>;
+    /**
+     * Opens the native location picker UI from Localé Kernel
+     * Shows a fullscreen map where the user can tap to select a location
+     *
+     * @param options - Configuration options for the map (e.g. readonly mode, initial coordinates)
+     * @returns Promise with selected coordinates { lat, lng } or null if cancelled
+     */
+    pickLocation(options?: PickLocationOptions): Promise<{
+        lat: number;
+        lng: number;
+    } | null>;
+    /**
+     * Reports the scroll direction to the Kernel, allowing the parent app
+     * to hide/show UI elements based on scroll behavior.
+     *
+     * @param direction - 'up' to show header, 'down' to hide header
+     */
+    reportScrollDirection(direction: "up" | "down"): void;
+    /**
+     * Requests the Kernel to initiate the login flow.
+     * The Kernel will save the current URL and redirect to the login page.
+     *
+     * @param intendedView - Optional view to navigate to after login (e.g., 'create', 'my-posts')
+     * This will be appended to the URL hash as #view=... so the mini-app can read it on load.
+     */
+    login(intendedView?: string): Promise<void>;
+    /**
+     * Updates the parent window's URL path.
+     * Useful for deep linking within the Mini-App using clean URLs.
+     * Example: If app is at /mascotas-perdidas, updateUrlPath('ABC-123')
+     * makes it /mascotas-perdidas/ABC-123
+     *
+     * @param slug - The slug or path segment to append/replace
+     */
+    updateUrlPath(slug: string): Promise<void>;
+}
+declare global {
+    interface Window {
+        LocaleApp: typeof LocaleApp;
+    }
+}
+//# sourceMappingURL=sdk.d.ts.map

package/dist/sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../src/sdk.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@locale-labs/miniapp-sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "SDK for Localé Mini-Apps - Bridge between Mini-Apps and the Localé Kernel",
   "main": "dist/sdk.js",
   "types": "dist/sdk.d.ts",
@@ -8,7 +8,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "esbuild src/sdk.ts --bundle --minify --format=iife --target=es2020 --outfile=dist/sdk.js",
+    "build": "bun run build:types && esbuild src/sdk.ts --bundle --minify --format=iife --target=es2020 --outfile=dist/sdk.js",
     "build:types": "tsc --emitDeclarationOnly --declaration --outDir dist"
   },
   "dependencies": {