@az-spaces/aza-miniapp-sdk 1.0.0

package/README.md

@@ -0,0 +1,182 @@
+# @jumpspaces/aza-miniapp-sdk
+
+TypeScript SDK for building **Aza Mini Apps**.
+
+The Aza native app injects `window.aza` into your WebView automatically — you don't ship any runtime code. This package gives you full TypeScript types and helpers so your IDE autocompletes correctly and your code is type-safe.
+
+---
+
+## Installation
+
+**From npm (public):**
+```bash
+npm install @jumpspaces/aza-miniapp-sdk
+```
+
+**From GitHub Packages (AZ-SPACES org members):**
+```bash
+# Add to your project's .npmrc:
+# @az-spaces:registry=https://npm.pkg.github.com/
+# //npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
+
+npm install @az-spaces/aza-miniapp-sdk
+```
+
+---
+
+## Quick start
+
+```ts
+import { waitForAza } from '@jumpspaces/aza-miniapp-sdk';
+
+const aza = await waitForAza();
+const user = await aza.getUser();
+console.log(`Hello, ${user.firstName}!`);
+```
+
+---
+
+## API reference
+
+### `waitForAza(timeoutMs?): Promise<AzaSDK>`
+
+Resolves with the bridge once it is ready. Safe to call at any point — if the bridge is already injected it resolves immediately; otherwise it waits for the `azaReady` event (dispatched before your page's first script runs).
+
+```ts
+const aza = await waitForAza();   // default 5 s timeout
+```
+
+### `getAza(): AzaSDK`
+
+Synchronous version. Throws `AzaNotAvailableError` if the bridge isn't present yet. Use `waitForAza()` unless you are certain the bridge is already available (e.g. inside an event handler that runs after `azaReady`).
+
+### `isInsideAza(): boolean`
+
+Returns `true` when running inside the Aza app. Use this to gracefully degrade when your app is also served standalone (useful during local development).
+
+```ts
+if (isInsideAza()) {
+  const aza = getAza();
+  // ...
+} else {
+  // show a "Open in Aza" banner
+}
+```
+
+### `useAza(timeoutMs?): AzaHookState` *(React only)*
+
+React hook version.
+
+```tsx
+import { useAza } from '@jumpspaces/aza-miniapp-sdk';
+
+function App() {
+  const { status, aza } = useAza();
+
+  if (status === 'loading')     return <Spinner />;
+  if (status === 'unavailable') return <p>Please open this in Aza.</p>;
+
+  return <button onClick={() => aza.close()}>Close</button>;
+}
+```
+
+---
+
+## `AzaSDK` methods
+
+All methods return a `Promise` that rejects with an `Error` if the operation fails or the required permission was not granted.
+
+### `aza.getUser() → Promise<AzaUser>`
+
+Returns the authenticated user's profile. Always available once the user has given consent.
+
+```ts
+const user = await aza.getUser();
+// { username, firstName, lastName, avatarUrl, phone?, email? }
+```
+
+`phone` and `email` are only present if your app declared `USER_PHONE` / `USER_EMAIL` in its permissions and the user approved them.
+
+### `aza.getBalance() → Promise<AzaBalance>`
+
+Returns the user's current wallet balance in GHS.
+
+Requires: `READ_BALANCE` permission.
+
+```ts
+const { balance } = await aza.getBalance();
+// { balance: 245.50 }
+```
+
+### `aza.requestPayment(params) → Promise<AzaPaymentResult>`
+
+Shows a **native confirmation dialog** in Aza before any money moves. The Promise resolves only after the user taps "Confirm".
+
+Requires: `MAKE_PAYMENTS` permission.
+
+```ts
+const result = await aza.requestPayment({
+  amount: 5.00,
+  recipientIdentifier: 'your_aza_username',  // your Aza account
+  note: 'Premium subscription',
+  idempotencyKey: crypto.randomUUID(),        // generate a fresh key per attempt
+});
+// { transactionId, status: 'COMPLETED', amount, recipientUsername, note }
+```
+
+**Important:** Generate a new `idempotencyKey` for every new payment intent. Reusing the same key on a retry is safe — Aza will return the original result without charging again.
+
+### `aza.close() → Promise<void>`
+
+Closes the mini app and returns the user to the Aza hub.
+
+### `aza.share(options) → Promise<void>`
+
+Opens the native Aza share sheet.
+
+```ts
+await aza.share({ title: 'Check this out', message: 'I just paid with Aza!' });
+```
+
+---
+
+## Declaring permissions
+
+Permissions must be declared when you submit your app via the Aza Developer dashboard. Users see them on a consent sheet on first launch.
+
+| Permission key      | What it grants                                    |
+|---------------------|---------------------------------------------------|
+| `USER_PROFILE`      | name, username, avatar (always required)          |
+| `USER_PHONE`        | phone number                                      |
+| `USER_EMAIL`        | email address                                     |
+| `MAKE_PAYMENTS`     | initiate payments from the user's Aza wallet      |
+| `READ_BALANCE`      | read the user's wallet balance                    |
+| `READ_TRANSACTIONS` | read recent transaction history *(coming soon)*   |
+
+---
+
+## Development
+
+During local development `window.aza` is not available (no native bridge). Use `isInsideAza()` to detect this and show a fallback, or mock the bridge:
+
+```ts
+// dev-mock.ts  (never ship this to production)
+if (process.env.NODE_ENV === 'development' && !window.aza) {
+  window.aza = {
+    version: 'mock',
+    getUser:        async () => ({ username: 'testuser', firstName: 'Test', lastName: 'User', avatarUrl: null }),
+    getBalance:     async () => ({ balance: 100.00 }),
+    requestPayment: async (p) => ({ transactionId: 'mock-tx', status: 'COMPLETED', amount: p.amount, recipientUsername: p.recipientIdentifier, note: p.note ?? null }),
+    close:          async () => {},
+    share:          async () => {},
+  };
+}
+```
+
+---
+
+## App URL requirements
+
+- Must use **HTTPS**. HTTP URLs are rejected at submission time.
+- Must be reachable from a mobile WebView (no localhost).
+- Your server must not block WebView user agents.

package/dist/index.d.mts

@@ -0,0 +1,145 @@
+/**
+ * @aza/miniapp-sdk
+ *
+ * Developer SDK for building Aza Mini Apps.
+ * The `window.aza` bridge is injected automatically by the Aza app at runtime —
+ * you do NOT need to include any runtime script. This package provides:
+ *
+ *   - TypeScript types for the entire `window.aza` API
+ *   - `getAza()` — safe accessor that throws if called outside Aza
+ *   - `waitForAza()` — Promise that resolves once the bridge is ready
+ *   - `isInsideAza()` — synchronous check
+ *
+ * Usage:
+ *   import { waitForAza } from '@aza/miniapp-sdk';
+ *
+ *   const aza = await waitForAza();
+ *   const user = await aza.getUser();
+ */
+interface AzaUser {
+    username: string;
+    firstName: string;
+    lastName: string;
+    avatarUrl: string | null;
+    /** Only present if USER_PHONE permission was granted. */
+    phone?: string;
+    /** Only present if USER_EMAIL permission was granted. */
+    email?: string;
+}
+interface AzaBalance {
+    balance: number;
+}
+interface AzaPaymentRequest {
+    /** Amount in GHS. */
+    amount: number;
+    /**
+     * The Aza username, phone number, or email of the payment recipient.
+     * Usually your own Aza account identifier as the mini-app developer.
+     */
+    recipientIdentifier: string;
+    /** Short description shown on the user's receipt. Max 200 chars. */
+    note?: string;
+    /**
+     * A unique key you generate per payment attempt.
+     * Aza will deduplicate based on this — safe to retry on network error.
+     */
+    idempotencyKey: string;
+}
+interface AzaPaymentResult {
+    transactionId: string;
+    status: 'PENDING' | 'COMPLETED' | 'FAILED';
+    amount: number;
+    recipientUsername: string;
+    note: string | null;
+}
+interface AzaShareOptions {
+    title?: string;
+    message: string;
+}
+interface AzaSDK {
+    /**
+     * Get the current user's profile.
+     * Always available after consent — no extra permission needed beyond USER_PROFILE.
+     */
+    getUser(): Promise<AzaUser>;
+    /**
+     * Get the user's current Aza wallet balance in GHS.
+     * Requires READ_BALANCE permission to be declared and consented.
+     */
+    getBalance(): Promise<AzaBalance>;
+    /**
+     * Request a payment from the user.
+     *
+     * The Aza app shows a native confirmation dialog — the user must tap "Confirm"
+     * before any money moves. Your Promise resolves only after confirmation.
+     *
+     * Requires MAKE_PAYMENTS permission to be declared and consented.
+     */
+    requestPayment(params: AzaPaymentRequest): Promise<AzaPaymentResult>;
+    /**
+     * Close this mini app and return the user to the Aza hub.
+     */
+    close(): Promise<void>;
+    /**
+     * Open the native Aza share sheet.
+     */
+    share(options: AzaShareOptions): Promise<void>;
+    /** SDK version string, e.g. "1.0.0" */
+    readonly version: string;
+}
+declare global {
+    interface Window {
+        /** Injected by the Aza native app before page content loads. */
+        aza?: AzaSDK;
+    }
+}
+/**
+ * Returns `true` when running inside the Aza app with the bridge available.
+ */
+declare function isInsideAza(): boolean;
+/**
+ * Synchronously returns the `window.aza` bridge.
+ * Throws `AzaNotAvailableError` if called outside the Aza app or before the bridge is ready.
+ */
+declare function getAza(): AzaSDK;
+/**
+ * Waits for the Aza bridge to be injected and returns it.
+ *
+ * - If `window.aza` is already available, resolves immediately.
+ * - If the page loads before the bridge (e.g. in dev), waits for the `azaReady` event.
+ * - Rejects after `timeoutMs` (default 5 000 ms) if the bridge never arrives.
+ *
+ * @example
+ * const aza = await waitForAza();
+ * const user = await aza.getUser();
+ */
+declare function waitForAza(timeoutMs?: number): Promise<AzaSDK>;
+/**
+ * Thrown when the Aza SDK is not available in the current environment.
+ */
+declare class AzaNotAvailableError extends Error {
+    constructor(message: string);
+}
+type AzaHookState = {
+    status: 'loading';
+} | {
+    status: 'ready';
+    aza: AzaSDK;
+} | {
+    status: 'unavailable';
+    error: AzaNotAvailableError;
+};
+/**
+ * React hook that resolves the Aza bridge.
+ *
+ * @example
+ * function MyApp() {
+ *   const { status, aza } = useAza();
+ *   if (status === 'loading') return <Spinner />;
+ *   if (status === 'unavailable') return <p>Open this in Aza</p>;
+ *   // aza is fully typed as AzaSDK
+ * }
+ */
+declare function useAza(timeoutMs?: number): AzaHookState;
+
+export { type AzaBalance, type AzaHookState, AzaNotAvailableError, type AzaPaymentRequest, type AzaPaymentResult, type AzaSDK, type AzaShareOptions, type AzaUser, getAza, isInsideAza, useAza, waitForAza };

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @aza/miniapp-sdk
+ *
+ * Developer SDK for building Aza Mini Apps.
+ * The `window.aza` bridge is injected automatically by the Aza app at runtime —
+ * you do NOT need to include any runtime script. This package provides:
+ *
+ *   - TypeScript types for the entire `window.aza` API
+ *   - `getAza()` — safe accessor that throws if called outside Aza
+ *   - `waitForAza()` — Promise that resolves once the bridge is ready
+ *   - `isInsideAza()` — synchronous check
+ *
+ * Usage:
+ *   import { waitForAza } from '@aza/miniapp-sdk';
+ *
+ *   const aza = await waitForAza();
+ *   const user = await aza.getUser();
+ */
+interface AzaUser {
+    username: string;
+    firstName: string;
+    lastName: string;
+    avatarUrl: string | null;
+    /** Only present if USER_PHONE permission was granted. */
+    phone?: string;
+    /** Only present if USER_EMAIL permission was granted. */
+    email?: string;
+}
+interface AzaBalance {
+    balance: number;
+}
+interface AzaPaymentRequest {
+    /** Amount in GHS. */
+    amount: number;
+    /**
+     * The Aza username, phone number, or email of the payment recipient.
+     * Usually your own Aza account identifier as the mini-app developer.
+     */
+    recipientIdentifier: string;
+    /** Short description shown on the user's receipt. Max 200 chars. */
+    note?: string;
+    /**
+     * A unique key you generate per payment attempt.
+     * Aza will deduplicate based on this — safe to retry on network error.
+     */
+    idempotencyKey: string;
+}
+interface AzaPaymentResult {
+    transactionId: string;
+    status: 'PENDING' | 'COMPLETED' | 'FAILED';
+    amount: number;
+    recipientUsername: string;
+    note: string | null;
+}
+interface AzaShareOptions {
+    title?: string;
+    message: string;
+}
+interface AzaSDK {
+    /**
+     * Get the current user's profile.
+     * Always available after consent — no extra permission needed beyond USER_PROFILE.
+     */
+    getUser(): Promise<AzaUser>;
+    /**
+     * Get the user's current Aza wallet balance in GHS.
+     * Requires READ_BALANCE permission to be declared and consented.
+     */
+    getBalance(): Promise<AzaBalance>;
+    /**
+     * Request a payment from the user.
+     *
+     * The Aza app shows a native confirmation dialog — the user must tap "Confirm"
+     * before any money moves. Your Promise resolves only after confirmation.
+     *
+     * Requires MAKE_PAYMENTS permission to be declared and consented.
+     */
+    requestPayment(params: AzaPaymentRequest): Promise<AzaPaymentResult>;
+    /**
+     * Close this mini app and return the user to the Aza hub.
+     */
+    close(): Promise<void>;
+    /**
+     * Open the native Aza share sheet.
+     */
+    share(options: AzaShareOptions): Promise<void>;
+    /** SDK version string, e.g. "1.0.0" */
+    readonly version: string;
+}
+declare global {
+    interface Window {
+        /** Injected by the Aza native app before page content loads. */
+        aza?: AzaSDK;
+    }
+}
+/**
+ * Returns `true` when running inside the Aza app with the bridge available.
+ */
+declare function isInsideAza(): boolean;
+/**
+ * Synchronously returns the `window.aza` bridge.
+ * Throws `AzaNotAvailableError` if called outside the Aza app or before the bridge is ready.
+ */
+declare function getAza(): AzaSDK;
+/**
+ * Waits for the Aza bridge to be injected and returns it.
+ *
+ * - If `window.aza` is already available, resolves immediately.
+ * - If the page loads before the bridge (e.g. in dev), waits for the `azaReady` event.
+ * - Rejects after `timeoutMs` (default 5 000 ms) if the bridge never arrives.
+ *
+ * @example
+ * const aza = await waitForAza();
+ * const user = await aza.getUser();
+ */
+declare function waitForAza(timeoutMs?: number): Promise<AzaSDK>;
+/**
+ * Thrown when the Aza SDK is not available in the current environment.
+ */
+declare class AzaNotAvailableError extends Error {
+    constructor(message: string);
+}
+type AzaHookState = {
+    status: 'loading';
+} | {
+    status: 'ready';
+    aza: AzaSDK;
+} | {
+    status: 'unavailable';
+    error: AzaNotAvailableError;
+};
+/**
+ * React hook that resolves the Aza bridge.
+ *
+ * @example
+ * function MyApp() {
+ *   const { status, aza } = useAza();
+ *   if (status === 'loading') return <Spinner />;
+ *   if (status === 'unavailable') return <p>Open this in Aza</p>;
+ *   // aza is fully typed as AzaSDK
+ * }
+ */
+declare function useAza(timeoutMs?: number): AzaHookState;
+
+export { type AzaBalance, type AzaHookState, AzaNotAvailableError, type AzaPaymentRequest, type AzaPaymentResult, type AzaSDK, type AzaShareOptions, type AzaUser, getAza, isInsideAza, useAza, waitForAza };

package/dist/index.js

@@ -0,0 +1,90 @@
+'use strict';
+
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/index.ts
+function isInsideAza() {
+  return typeof window !== "undefined" && typeof window.aza !== "undefined";
+}
+function getAza() {
+  if (!isInsideAza()) {
+    throw new AzaNotAvailableError(
+      "window.aza is not available. Make sure your app is running inside the Aza mini app player."
+    );
+  }
+  return window.aza;
+}
+function waitForAza(timeoutMs = 5e3) {
+  if (isInsideAza()) {
+    return Promise.resolve(window.aza);
+  }
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      window.removeEventListener("azaReady", onReady);
+      reject(new AzaNotAvailableError(
+        `Aza bridge did not initialise within ${timeoutMs}ms. Make sure your app is running inside the Aza mini app player.`
+      ));
+    }, timeoutMs);
+    function onReady() {
+      clearTimeout(timer);
+      window.removeEventListener("azaReady", onReady);
+      if (window.aza) {
+        resolve(window.aza);
+      } else {
+        reject(new AzaNotAvailableError("azaReady fired but window.aza is still undefined."));
+      }
+    }
+    window.addEventListener("azaReady", onReady);
+  });
+}
+var AzaNotAvailableError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AzaNotAvailableError";
+  }
+};
+function useAza(timeoutMs = 5e3) {
+  const React = _requireReact();
+  if (!React) {
+    throw new Error(
+      "useAza() requires React. Install react and react-dom, or use waitForAza() instead."
+    );
+  }
+  const [state, setState] = React.useState(
+    isInsideAza() ? { status: "ready", aza: window.aza } : { status: "loading" }
+  );
+  React.useEffect(() => {
+    if (state.status === "ready") return;
+    let cancelled = false;
+    waitForAza(timeoutMs).then((aza) => {
+      if (!cancelled) setState({ status: "ready", aza });
+    }).catch((error) => {
+      if (!cancelled) setState({ status: "unavailable", error });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+  return state;
+}
+function _requireReact() {
+  try {
+    if (typeof __require === "undefined") return null;
+    return __require("react");
+  } catch (e) {
+    return null;
+  }
+}
+
+exports.AzaNotAvailableError = AzaNotAvailableError;
+exports.getAza = getAza;
+exports.isInsideAza = isInsideAza;
+exports.useAza = useAza;
+exports.waitForAza = waitForAza;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @aza/miniapp-sdk\n *\n * Developer SDK for building Aza Mini Apps.\n * The `window.aza` bridge is injected automatically by the Aza app at runtime —\n * you do NOT need to include any runtime script. This package provides:\n *\n *   - TypeScript types for the entire `window.aza` API\n *   - `getAza()` — safe accessor that throws if called outside Aza\n *   - `waitForAza()` — Promise that resolves once the bridge is ready\n *   - `isInsideAza()` — synchronous check\n *\n * Usage:\n *   import { waitForAza } from '@aza/miniapp-sdk';\n *\n *   const aza = await waitForAza();\n *   const user = await aza.getUser();\n */\n\n// ─── Types ────────────────────────────────────────────────────────────────────\n\nexport interface AzaUser {\n  username: string;\n  firstName: string;\n  lastName: string;\n  avatarUrl: string | null;\n  /** Only present if USER_PHONE permission was granted. */\n  phone?: string;\n  /** Only present if USER_EMAIL permission was granted. */\n  email?: string;\n}\n\nexport interface AzaBalance {\n  balance: number;\n}\n\nexport interface AzaPaymentRequest {\n  /** Amount in GHS. */\n  amount: number;\n  /**\n   * The Aza username, phone number, or email of the payment recipient.\n   * Usually your own Aza account identifier as the mini-app developer.\n   */\n  recipientIdentifier: string;\n  /** Short description shown on the user's receipt. Max 200 chars. */\n  note?: string;\n  /**\n   * A unique key you generate per payment attempt.\n   * Aza will deduplicate based on this — safe to retry on network error.\n   */\n  idempotencyKey: string;\n}\n\nexport interface AzaPaymentResult {\n  transactionId: string;\n  status: 'PENDING' | 'COMPLETED' | 'FAILED';\n  amount: number;\n  recipientUsername: string;\n  note: string | null;\n}\n\nexport interface AzaShareOptions {\n  title?: string;\n  message: string;\n}\n\nexport interface AzaSDK {\n  /**\n   * Get the current user's profile.\n   * Always available after consent — no extra permission needed beyond USER_PROFILE.\n   */\n  getUser(): Promise<AzaUser>;\n\n  /**\n   * Get the user's current Aza wallet balance in GHS.\n   * Requires READ_BALANCE permission to be declared and consented.\n   */\n  getBalance(): Promise<AzaBalance>;\n\n  /**\n   * Request a payment from the user.\n   *\n   * The Aza app shows a native confirmation dialog — the user must tap \"Confirm\"\n   * before any money moves. Your Promise resolves only after confirmation.\n   *\n   * Requires MAKE_PAYMENTS permission to be declared and consented.\n   */\n  requestPayment(params: AzaPaymentRequest): Promise<AzaPaymentResult>;\n\n  /**\n   * Close this mini app and return the user to the Aza hub.\n   */\n  close(): Promise<void>;\n\n  /**\n   * Open the native Aza share sheet.\n   */\n  share(options: AzaShareOptions): Promise<void>;\n\n  /** SDK version string, e.g. \"1.0.0\" */\n  readonly version: string;\n}\n\n// ─── Global augmentation ──────────────────────────────────────────────────────\n\ndeclare global {\n  interface Window {\n    /** Injected by the Aza native app before page content loads. */\n    aza?: AzaSDK;\n  }\n}\n\n// ─── Helpers ──────────────────────────────────────────────────────────────────\n\n/**\n * Returns `true` when running inside the Aza app with the bridge available.\n */\nexport function isInsideAza(): boolean {\n  return typeof window !== 'undefined' && typeof window.aza !== 'undefined';\n}\n\n/**\n * Synchronously returns the `window.aza` bridge.\n * Throws `AzaNotAvailableError` if called outside the Aza app or before the bridge is ready.\n */\nexport function getAza(): AzaSDK {\n  if (!isInsideAza()) {\n    throw new AzaNotAvailableError(\n      'window.aza is not available. Make sure your app is running inside the Aza mini app player.'\n    );\n  }\n  return window.aza!;\n}\n\n/**\n * Waits for the Aza bridge to be injected and returns it.\n *\n * - If `window.aza` is already available, resolves immediately.\n * - If the page loads before the bridge (e.g. in dev), waits for the `azaReady` event.\n * - Rejects after `timeoutMs` (default 5 000 ms) if the bridge never arrives.\n *\n * @example\n * const aza = await waitForAza();\n * const user = await aza.getUser();\n */\nexport function waitForAza(timeoutMs = 5_000): Promise<AzaSDK> {\n  if (isInsideAza()) {\n    return Promise.resolve(window.aza!);\n  }\n\n  return new Promise<AzaSDK>((resolve, reject) => {\n    const timer = setTimeout(() => {\n      window.removeEventListener('azaReady', onReady);\n      reject(new AzaNotAvailableError(\n        `Aza bridge did not initialise within ${timeoutMs}ms. ` +\n        'Make sure your app is running inside the Aza mini app player.'\n      ));\n    }, timeoutMs);\n\n    function onReady() {\n      clearTimeout(timer);\n      window.removeEventListener('azaReady', onReady);\n      if (window.aza) {\n        resolve(window.aza);\n      } else {\n        reject(new AzaNotAvailableError('azaReady fired but window.aza is still undefined.'));\n      }\n    }\n\n    window.addEventListener('azaReady', onReady);\n  });\n}\n\n/**\n * Thrown when the Aza SDK is not available in the current environment.\n */\nexport class AzaNotAvailableError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'AzaNotAvailableError';\n  }\n}\n\n// ─── React hook (optional, tree-shakeable) ────────────────────────────────────\n\nexport type AzaHookState =\n  | { status: 'loading' }\n  | { status: 'ready'; aza: AzaSDK }\n  | { status: 'unavailable'; error: AzaNotAvailableError };\n\n/**\n * React hook that resolves the Aza bridge.\n *\n * @example\n * function MyApp() {\n *   const { status, aza } = useAza();\n *   if (status === 'loading') return <Spinner />;\n *   if (status === 'unavailable') return <p>Open this in Aza</p>;\n *   // aza is fully typed as AzaSDK\n * }\n */\nexport function useAza(timeoutMs = 5_000): AzaHookState {\n  // Lazy require React so the rest of the SDK works without React installed\n  // (plain HTML / Vue / Svelte apps don't need React)\n  const React = _requireReact();\n  if (!React) {\n    throw new Error(\n      'useAza() requires React. Install react and react-dom, or use waitForAza() instead.'\n    );\n  }\n\n  const [state, setState] = React.useState<AzaHookState>(\n    isInsideAza() ? { status: 'ready', aza: window.aza! } : { status: 'loading' }\n  );\n\n  React.useEffect(() => {\n    if (state.status === 'ready') return;\n    let cancelled = false;\n\n    waitForAza(timeoutMs)\n      .then((aza) => { if (!cancelled) setState({ status: 'ready', aza }); })\n      .catch((error) => { if (!cancelled) setState({ status: 'unavailable', error }); });\n\n    return () => { cancelled = true; };\n  }, []);\n\n  return state;\n}\n\n// `require` is resolved by bundlers (webpack/vite/esbuild) at build time.\n// Declaring it here avoids a dependency on @types/node while staying type-safe.\ndeclare const require: undefined | ((id: string) => unknown);\n\nfunction _requireReact(): typeof import('react') | null {\n  try {\n    if (typeof require === 'undefined') return null;\n    return require('react') as typeof import('react');\n  } catch {\n    return null;\n  }\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,84 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/index.ts
+function isInsideAza() {
+  return typeof window !== "undefined" && typeof window.aza !== "undefined";
+}
+function getAza() {
+  if (!isInsideAza()) {
+    throw new AzaNotAvailableError(
+      "window.aza is not available. Make sure your app is running inside the Aza mini app player."
+    );
+  }
+  return window.aza;
+}
+function waitForAza(timeoutMs = 5e3) {
+  if (isInsideAza()) {
+    return Promise.resolve(window.aza);
+  }
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      window.removeEventListener("azaReady", onReady);
+      reject(new AzaNotAvailableError(
+        `Aza bridge did not initialise within ${timeoutMs}ms. Make sure your app is running inside the Aza mini app player.`
+      ));
+    }, timeoutMs);
+    function onReady() {
+      clearTimeout(timer);
+      window.removeEventListener("azaReady", onReady);
+      if (window.aza) {
+        resolve(window.aza);
+      } else {
+        reject(new AzaNotAvailableError("azaReady fired but window.aza is still undefined."));
+      }
+    }
+    window.addEventListener("azaReady", onReady);
+  });
+}
+var AzaNotAvailableError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AzaNotAvailableError";
+  }
+};
+function useAza(timeoutMs = 5e3) {
+  const React = _requireReact();
+  if (!React) {
+    throw new Error(
+      "useAza() requires React. Install react and react-dom, or use waitForAza() instead."
+    );
+  }
+  const [state, setState] = React.useState(
+    isInsideAza() ? { status: "ready", aza: window.aza } : { status: "loading" }
+  );
+  React.useEffect(() => {
+    if (state.status === "ready") return;
+    let cancelled = false;
+    waitForAza(timeoutMs).then((aza) => {
+      if (!cancelled) setState({ status: "ready", aza });
+    }).catch((error) => {
+      if (!cancelled) setState({ status: "unavailable", error });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+  return state;
+}
+function _requireReact() {
+  try {
+    if (typeof __require === "undefined") return null;
+    return __require("react");
+  } catch (e) {
+    return null;
+  }
+}
+
+export { AzaNotAvailableError, getAza, isInsideAza, useAza, waitForAza };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * @aza/miniapp-sdk\n *\n * Developer SDK for building Aza Mini Apps.\n * The `window.aza` bridge is injected automatically by the Aza app at runtime —\n * you do NOT need to include any runtime script. This package provides:\n *\n *   - TypeScript types for the entire `window.aza` API\n *   - `getAza()` — safe accessor that throws if called outside Aza\n *   - `waitForAza()` — Promise that resolves once the bridge is ready\n *   - `isInsideAza()` — synchronous check\n *\n * Usage:\n *   import { waitForAza } from '@aza/miniapp-sdk';\n *\n *   const aza = await waitForAza();\n *   const user = await aza.getUser();\n */\n\n// ─── Types ────────────────────────────────────────────────────────────────────\n\nexport interface AzaUser {\n  username: string;\n  firstName: string;\n  lastName: string;\n  avatarUrl: string | null;\n  /** Only present if USER_PHONE permission was granted. */\n  phone?: string;\n  /** Only present if USER_EMAIL permission was granted. */\n  email?: string;\n}\n\nexport interface AzaBalance {\n  balance: number;\n}\n\nexport interface AzaPaymentRequest {\n  /** Amount in GHS. */\n  amount: number;\n  /**\n   * The Aza username, phone number, or email of the payment recipient.\n   * Usually your own Aza account identifier as the mini-app developer.\n   */\n  recipientIdentifier: string;\n  /** Short description shown on the user's receipt. Max 200 chars. */\n  note?: string;\n  /**\n   * A unique key you generate per payment attempt.\n   * Aza will deduplicate based on this — safe to retry on network error.\n   */\n  idempotencyKey: string;\n}\n\nexport interface AzaPaymentResult {\n  transactionId: string;\n  status: 'PENDING' | 'COMPLETED' | 'FAILED';\n  amount: number;\n  recipientUsername: string;\n  note: string | null;\n}\n\nexport interface AzaShareOptions {\n  title?: string;\n  message: string;\n}\n\nexport interface AzaSDK {\n  /**\n   * Get the current user's profile.\n   * Always available after consent — no extra permission needed beyond USER_PROFILE.\n   */\n  getUser(): Promise<AzaUser>;\n\n  /**\n   * Get the user's current Aza wallet balance in GHS.\n   * Requires READ_BALANCE permission to be declared and consented.\n   */\n  getBalance(): Promise<AzaBalance>;\n\n  /**\n   * Request a payment from the user.\n   *\n   * The Aza app shows a native confirmation dialog — the user must tap \"Confirm\"\n   * before any money moves. Your Promise resolves only after confirmation.\n   *\n   * Requires MAKE_PAYMENTS permission to be declared and consented.\n   */\n  requestPayment(params: AzaPaymentRequest): Promise<AzaPaymentResult>;\n\n  /**\n   * Close this mini app and return the user to the Aza hub.\n   */\n  close(): Promise<void>;\n\n  /**\n   * Open the native Aza share sheet.\n   */\n  share(options: AzaShareOptions): Promise<void>;\n\n  /** SDK version string, e.g. \"1.0.0\" */\n  readonly version: string;\n}\n\n// ─── Global augmentation ──────────────────────────────────────────────────────\n\ndeclare global {\n  interface Window {\n    /** Injected by the Aza native app before page content loads. */\n    aza?: AzaSDK;\n  }\n}\n\n// ─── Helpers ──────────────────────────────────────────────────────────────────\n\n/**\n * Returns `true` when running inside the Aza app with the bridge available.\n */\nexport function isInsideAza(): boolean {\n  return typeof window !== 'undefined' && typeof window.aza !== 'undefined';\n}\n\n/**\n * Synchronously returns the `window.aza` bridge.\n * Throws `AzaNotAvailableError` if called outside the Aza app or before the bridge is ready.\n */\nexport function getAza(): AzaSDK {\n  if (!isInsideAza()) {\n    throw new AzaNotAvailableError(\n      'window.aza is not available. Make sure your app is running inside the Aza mini app player.'\n    );\n  }\n  return window.aza!;\n}\n\n/**\n * Waits for the Aza bridge to be injected and returns it.\n *\n * - If `window.aza` is already available, resolves immediately.\n * - If the page loads before the bridge (e.g. in dev), waits for the `azaReady` event.\n * - Rejects after `timeoutMs` (default 5 000 ms) if the bridge never arrives.\n *\n * @example\n * const aza = await waitForAza();\n * const user = await aza.getUser();\n */\nexport function waitForAza(timeoutMs = 5_000): Promise<AzaSDK> {\n  if (isInsideAza()) {\n    return Promise.resolve(window.aza!);\n  }\n\n  return new Promise<AzaSDK>((resolve, reject) => {\n    const timer = setTimeout(() => {\n      window.removeEventListener('azaReady', onReady);\n      reject(new AzaNotAvailableError(\n        `Aza bridge did not initialise within ${timeoutMs}ms. ` +\n        'Make sure your app is running inside the Aza mini app player.'\n      ));\n    }, timeoutMs);\n\n    function onReady() {\n      clearTimeout(timer);\n      window.removeEventListener('azaReady', onReady);\n      if (window.aza) {\n        resolve(window.aza);\n      } else {\n        reject(new AzaNotAvailableError('azaReady fired but window.aza is still undefined.'));\n      }\n    }\n\n    window.addEventListener('azaReady', onReady);\n  });\n}\n\n/**\n * Thrown when the Aza SDK is not available in the current environment.\n */\nexport class AzaNotAvailableError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'AzaNotAvailableError';\n  }\n}\n\n// ─── React hook (optional, tree-shakeable) ────────────────────────────────────\n\nexport type AzaHookState =\n  | { status: 'loading' }\n  | { status: 'ready'; aza: AzaSDK }\n  | { status: 'unavailable'; error: AzaNotAvailableError };\n\n/**\n * React hook that resolves the Aza bridge.\n *\n * @example\n * function MyApp() {\n *   const { status, aza } = useAza();\n *   if (status === 'loading') return <Spinner />;\n *   if (status === 'unavailable') return <p>Open this in Aza</p>;\n *   // aza is fully typed as AzaSDK\n * }\n */\nexport function useAza(timeoutMs = 5_000): AzaHookState {\n  // Lazy require React so the rest of the SDK works without React installed\n  // (plain HTML / Vue / Svelte apps don't need React)\n  const React = _requireReact();\n  if (!React) {\n    throw new Error(\n      'useAza() requires React. Install react and react-dom, or use waitForAza() instead.'\n    );\n  }\n\n  const [state, setState] = React.useState<AzaHookState>(\n    isInsideAza() ? { status: 'ready', aza: window.aza! } : { status: 'loading' }\n  );\n\n  React.useEffect(() => {\n    if (state.status === 'ready') return;\n    let cancelled = false;\n\n    waitForAza(timeoutMs)\n      .then((aza) => { if (!cancelled) setState({ status: 'ready', aza }); })\n      .catch((error) => { if (!cancelled) setState({ status: 'unavailable', error }); });\n\n    return () => { cancelled = true; };\n  }, []);\n\n  return state;\n}\n\n// `require` is resolved by bundlers (webpack/vite/esbuild) at build time.\n// Declaring it here avoids a dependency on @types/node while staying type-safe.\ndeclare const require: undefined | ((id: string) => unknown);\n\nfunction _requireReact(): typeof import('react') | null {\n  try {\n    if (typeof require === 'undefined') return null;\n    return require('react') as typeof import('react');\n  } catch {\n    return null;\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@az-spaces/aza-miniapp-sdk",
+  "version": "1.0.0",
+  "description": "SDK for building Aza Mini Apps. Provides TypeScript types and bridge helpers for window.aza.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "publish:npm": "npm publish --access public --registry https://registry.npmjs.org/",
+    "publish:github": "npm publish --access public --registry https://npm.pkg.github.com/"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AZ-SPACES/project404.git"
+  },
+  "peerDependencies": {
+    "react": ">=17"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true }
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "@types/react": "^18.0.0"
+  },
+  "keywords": ["aza", "miniapp", "sdk", "fintech", "ghana"],
+  "license": "MIT"
+}