flit-baas 1.0.0

package/dist/index.cjs

@@ -0,0 +1,766 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+// src/errors.ts
+var FlitError = class extends Error {
+  code;
+  constructor(message, code = "FLIT_ERROR") {
+    super(message);
+    this.name = "FlitError";
+    this.code = code;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var FlitAPIError = class extends FlitError {
+  status;
+  details;
+  constructor(message, status, code = "API_ERROR", details) {
+    super(message, code);
+    this.name = "FlitAPIError";
+    this.status = status;
+    this.details = details;
+  }
+};
+var FlitPaymentError = class extends FlitError {
+  operator;
+  transactionId;
+  constructor(message, operator, transactionId) {
+    super(message, "PAYMENT_FAILED");
+    this.name = "FlitPaymentError";
+    this.operator = operator;
+    this.transactionId = transactionId;
+  }
+};
+var FlitAuthError = class extends FlitError {
+  constructor(message, code = "AUTH_ERROR") {
+    super(message, code);
+    this.name = "FlitAuthError";
+  }
+};
+
+// src/collection.ts
+var Collection = class {
+  client;
+  name;
+  constructor(client, name) {
+    this.client = client;
+    this.name = name.trim();
+  }
+  /**
+   * Helper to normalize a record returned from the PostgreSQL JSONB document store.
+   * Flattens { id, createdAt, updatedAt, data: { ... } } into a single intuitive object.
+   */
+  normalizeRecord(raw) {
+    if (!raw || typeof raw !== "object") return raw;
+    const { id, createdAt, updatedAt, data, ...rest } = raw;
+    const documentData = typeof data === "object" && data !== null ? data : {};
+    return {
+      id,
+      createdAt,
+      updatedAt,
+      ...documentData,
+      ...rest
+    };
+  }
+  /**
+   * Find documents matching optional filters, with pagination and sorting
+   * @param filter Key-value pairs to match against document properties
+   * @param options Query options (limit, offset, orderBy, order)
+   */
+  async find(filter, options = {}) {
+    const queryParams = new URLSearchParams();
+    if (options.limit !== void 0) {
+      queryParams.set("limit", String(options.limit));
+    }
+    if (options.offset !== void 0) {
+      queryParams.set("offset", String(options.offset));
+    }
+    if (options.orderBy) {
+      queryParams.set("orderBy", String(options.orderBy));
+    }
+    if (options.order) {
+      queryParams.set("order", options.order);
+    }
+    let res;
+    if (filter && Object.keys(filter).length > 0) {
+      res = await this.client.request(
+        `/api/baas/collections/${this.name}/query`,
+        {
+          method: "POST",
+          body: JSON.stringify({
+            appId: this.client.appId,
+            filter,
+            limit: options.limit,
+            offset: options.offset,
+            orderBy: options.orderBy,
+            order: options.order
+          })
+        }
+      );
+    } else {
+      const qs = queryParams.toString() ? `?${queryParams.toString()}` : "";
+      res = await this.client.request(
+        `/api/apps/${this.client.appId}/baas/${this.name}${qs}`,
+        { method: "GET" }
+      );
+    }
+    const records = res.records || [];
+    return records.map((r) => this.normalizeRecord(r));
+  }
+  /**
+   * Find a single document by its unique ID
+   * @param id Document UUID
+   */
+  async findById(id) {
+    if (!id) return null;
+    try {
+      const res = await this.client.request(
+        `/api/apps/${this.client.appId}/baas/${this.name}?id=${encodeURIComponent(id)}`,
+        { method: "GET" }
+      );
+      if (!res.record) return null;
+      return this.normalizeRecord(res.record);
+    } catch (err) {
+      if (err?.status === 404) return null;
+      throw err;
+    }
+  }
+  /**
+   * Insert a new document into the collection
+   * @param data The document payload (without id, createdAt, updatedAt)
+   */
+  async insert(data) {
+    const res = await this.client.request(
+      `/api/apps/${this.client.appId}/baas/${this.name}`,
+      {
+        method: "POST",
+        body: JSON.stringify({ data })
+      }
+    );
+    if (!res.record) {
+      throw new Error(`Failed to insert document into collection '${this.name}'`);
+    }
+    return this.normalizeRecord(res.record);
+  }
+  /**
+   * Insert multiple documents sequentially
+   * @param items Array of document payloads
+   */
+  async insertMany(items) {
+    const results = [];
+    for (const item of items) {
+      const inserted = await this.insert(item);
+      results.push(inserted);
+    }
+    return results;
+  }
+  /**
+   * Update an existing document by ID
+   * @param id Document UUID
+   * @param data Partial update payload
+   */
+  async update(id, data) {
+    if (!id) {
+      throw new Error("Document 'id' is required for update operation");
+    }
+    const res = await this.client.request(
+      `/api/apps/${this.client.appId}/baas/${this.name}`,
+      {
+        method: "PATCH",
+        body: JSON.stringify({ id, data })
+      }
+    );
+    if (!res.record) {
+      throw new Error(`Failed to update document with id '${id}' in collection '${this.name}'`);
+    }
+    return this.normalizeRecord(res.record);
+  }
+  /**
+   * Delete a document by ID
+   * @param id Document UUID
+   */
+  async delete(id) {
+    if (!id) {
+      throw new Error("Document 'id' is required for delete operation");
+    }
+    const res = await this.client.request(
+      `/api/apps/${this.client.appId}/baas/${this.name}?id=${encodeURIComponent(id)}`,
+      { method: "DELETE" }
+    );
+    return !!res.success;
+  }
+  /**
+   * Count documents matching an optional filter
+   */
+  async count(filter) {
+    const results = await this.find(filter, { limit: 1 });
+    return results.length;
+  }
+};
+
+// src/payments.ts
+var FlitPayments = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Initiate a Mobile Money STK Push deposit (Orange Money, MTN MoMo, Wave, etc.)
+   * @param order Payment order specifications
+   */
+  async initiate(order) {
+    if (!order.phone || !order.amount || !order.operator) {
+      throw new FlitPaymentError(
+        "Missing required payment parameters: phone, amount, and operator are mandatory.",
+        order.operator
+      );
+    }
+    if (order.amount <= 0) {
+      throw new FlitPaymentError("Payment amount must be greater than zero.", order.operator);
+    }
+    try {
+      const payload = {
+        appId: this.client.appId,
+        operator: order.operator.toUpperCase(),
+        phone: order.phone.replace(/[\s-]/g, ""),
+        amount: order.amount,
+        currency: order.currency || "XAF",
+        title: order.title || `Paiement ${order.operator}`,
+        customerName: order.customerName,
+        customerEmail: order.customerEmail,
+        metadata: order.metadata || {}
+      };
+      const res = await this.client.request(
+        "/api/payments/deposit",
+        {
+          method: "POST",
+          body: JSON.stringify(payload)
+        }
+      );
+      return res;
+    } catch (err) {
+      throw new FlitPaymentError(
+        err.message || "Failed to initiate Mobile Money payment",
+        order.operator
+      );
+    }
+  }
+  /**
+   * Retrieve current real-time status of a payment transaction
+   * @param transactionId Transaction or deposit reference
+   */
+  async getStatus(transactionId) {
+    if (!transactionId) {
+      throw new FlitPaymentError("transactionId is required to query payment status");
+    }
+    return this.client.request(
+      `/api/payments/status?transactionId=${encodeURIComponent(transactionId)}&appId=${encodeURIComponent(
+        this.client.appId
+      )}`,
+      { method: "GET" }
+    );
+  }
+  /**
+   * Poll for transaction completion until a final status (SUCCESS, FAILED, EXPIRED) is reached
+   * @param transactionId Transaction reference
+   * @param options Polling configuration (timeoutMs default 60000ms, intervalMs default 3000ms)
+   */
+  async waitForStatus(transactionId, options = {}) {
+    const timeoutMs = options.timeoutMs || 6e4;
+    const intervalMs = options.intervalMs || 3e3;
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeoutMs) {
+      const status = await this.getStatus(transactionId);
+      if (status.status === "SUCCESS" || status.status === "FAILED" || status.status === "EXPIRED") {
+        return status;
+      }
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+    throw new FlitPaymentError(
+      `Payment status polling timed out after ${timeoutMs}ms for transaction ${transactionId}`
+    );
+  }
+};
+
+// src/cookies.ts
+var DEFAULT_COOKIE_NAME = "flit_session";
+var DEFAULT_MAX_AGE = 30 * 24 * 60 * 60;
+async function deriveKey(secret) {
+  const enc = new TextEncoder();
+  const secretBytes = enc.encode(secret);
+  const hash = await crypto.subtle.digest("SHA-256", secretBytes);
+  return crypto.subtle.importKey(
+    "raw",
+    hash,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
+}
+async function encryptSession(payload, secretKey) {
+  const key = await deriveKey(secretKey);
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const encodedPayload = new TextEncoder().encode(JSON.stringify(payload));
+  const cipherBuffer = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv },
+    key,
+    encodedPayload
+  );
+  const combined = new Uint8Array(iv.length + cipherBuffer.byteLength);
+  combined.set(iv, 0);
+  combined.set(new Uint8Array(cipherBuffer), iv.length);
+  let binary = "";
+  for (let i = 0; i < combined.length; i++) {
+    binary += String.fromCharCode(combined[i]);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+async function decryptSession(encryptedText, secretKey) {
+  try {
+    const key = await deriveKey(secretKey);
+    let base64 = encryptedText.replace(/-/g, "+").replace(/_/g, "/");
+    while (base64.length % 4) {
+      base64 += "=";
+    }
+    const binary = atob(base64);
+    const combined = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      combined[i] = binary.charCodeAt(i);
+    }
+    if (combined.length < 12 + 16) {
+      return null;
+    }
+    const iv = combined.slice(0, 12);
+    const ciphertext = combined.slice(12);
+    const decryptedBuffer = await crypto.subtle.decrypt(
+      { name: "AES-GCM", iv },
+      key,
+      ciphertext
+    );
+    const decoded = new TextDecoder().decode(decryptedBuffer);
+    const session = JSON.parse(decoded);
+    if (session.expiresAt && Date.now() > session.expiresAt) {
+      return null;
+    }
+    return session;
+  } catch {
+    return null;
+  }
+}
+function buildSetCookieHeader(value, options = {}) {
+  const name = options.name || DEFAULT_COOKIE_NAME;
+  const path = options.path || "/";
+  const maxAge = options.maxAge !== void 0 ? options.maxAge : DEFAULT_MAX_AGE;
+  const secure = options.secure !== false;
+  const httpOnly = options.httpOnly !== false;
+  const sameSite = options.sameSite || "Lax";
+  const parts = [`${name}=${encodeURIComponent(value)}`, `Path=${path}`];
+  if (maxAge >= 0) {
+    parts.push(`Max-Age=${maxAge}`);
+    const expires = new Date(Date.now() + maxAge * 1e3).toUTCString();
+    parts.push(`Expires=${expires}`);
+  }
+  if (options.domain) {
+    parts.push(`Domain=${options.domain}`);
+  }
+  {
+    parts.push(`SameSite=${sameSite}`);
+  }
+  if (secure) {
+    parts.push("Secure");
+  }
+  if (httpOnly) {
+    parts.push("HttpOnly");
+  }
+  return parts.join("; ");
+}
+function buildClearCookieHeader(options = {}) {
+  return buildSetCookieHeader("", {
+    ...options,
+    maxAge: 0
+  });
+}
+function parseCookieFromHeader(cookieHeader, cookieName = DEFAULT_COOKIE_NAME) {
+  if (!cookieHeader) return null;
+  const cookies = cookieHeader.split(";");
+  for (const c of cookies) {
+    const [key, ...valParts] = c.trim().split("=");
+    if (key === cookieName) {
+      return decodeURIComponent(valParts.join("="));
+    }
+  }
+  return null;
+}
+
+// src/auth.ts
+var FlitAuth = class {
+  client;
+  storage;
+  currentSession = null;
+  storageKey;
+  constructor(client, storage) {
+    this.client = client;
+    this.storage = storage;
+    this.storageKey = `flit_auth_session_${this.client.appId}`;
+    this.initSession();
+  }
+  /**
+   * Initialize session securely.
+   * If a custom storage adapter was provided (e.g. secure encrypted cookie store),
+   * load the session from it. Otherwise keep in-memory only (zero XSS localStorage exposure).
+   */
+  async initSession() {
+    if (this.storage) {
+      try {
+        const stored = await this.storage.getItem(this.storageKey);
+        if (stored) {
+          this.currentSession = JSON.parse(stored);
+        }
+      } catch {
+      }
+    }
+  }
+  async persistSession(session) {
+    this.currentSession = session;
+    if (this.storage) {
+      try {
+        if (session) {
+          await this.storage.setItem(this.storageKey, JSON.stringify(session));
+        } else {
+          await this.storage.removeItem(this.storageKey);
+        }
+      } catch {
+      }
+    }
+  }
+  /**
+   * Register a new user
+   */
+  async signUp(credentials) {
+    if (!credentials.email) {
+      throw new FlitAuthError("Email is required for registration");
+    }
+    try {
+      const res = await this.client.request("/api/auth/register", {
+        method: "POST",
+        body: JSON.stringify({
+          appId: this.client.appId,
+          ...credentials
+        })
+      });
+      if (res.session) {
+        await this.persistSession(res.session);
+      }
+      return res;
+    } catch (err) {
+      throw new FlitAuthError(err.message || "Registration failed");
+    }
+  }
+  /**
+   * Sign in an existing user with email and password
+   */
+  async signInWithPassword(credentials) {
+    if (!credentials.email || !credentials.password) {
+      throw new FlitAuthError("Email and password are required");
+    }
+    try {
+      const res = await this.client.request("/api/auth/login", {
+        method: "POST",
+        body: JSON.stringify({
+          appId: this.client.appId,
+          ...credentials
+        })
+      });
+      if (res.session) {
+        await this.persistSession(res.session);
+      }
+      return res;
+    } catch (err) {
+      throw new FlitAuthError(err.message || "Authentication failed");
+    }
+  }
+  /**
+   * Sign out the currently authenticated user
+   */
+  async signOut() {
+    await this.persistSession(null);
+  }
+  /**
+   * Get current session if available (in-memory)
+   */
+  getSession() {
+    return this.currentSession;
+  }
+  /**
+   * Get current user if authenticated
+   */
+  getUser() {
+    return this.currentSession?.user || null;
+  }
+  /**
+   * Server-Side Helper: Generate a cryptographically encrypted (AES-256-GCM) HttpOnly Set-Cookie header.
+   * Immunizes authentication tokens against XSS attacks.
+   *
+   * @param session The authenticated session to encrypt
+   * @param secretKey Encryption key (defaults to client's secret apiKey or appId)
+   * @param options Custom cookie attributes (Path, Domain, Max-Age, etc.)
+   */
+  async createSessionCookie(session, secretKey, options) {
+    const key = secretKey || this.client.apiKey || this.client.appId;
+    const payload = {
+      token: session.token,
+      userId: session.user.id,
+      appId: this.client.appId,
+      expiresAt: session.expiresAt,
+      email: session.user.email
+    };
+    const encrypted = await encryptSession(payload, key);
+    return buildSetCookieHeader(encrypted, {
+      httpOnly: true,
+      secure: true,
+      sameSite: "Lax",
+      path: "/",
+      ...options
+    });
+  }
+  /**
+   * Server-Side Helper: Decrypt and verify an incoming HttpOnly cookie header using AES-256-GCM.
+   *
+   * @param cookieHeader The incoming Cookie request header string
+   * @param secretKey Encryption key (must match the key used in createSessionCookie)
+   */
+  async verifySessionCookie(cookieHeader, secretKey, cookieName) {
+    const raw = parseCookieFromHeader(cookieHeader, cookieName);
+    if (!raw) return null;
+    const key = secretKey || this.client.apiKey || this.client.appId;
+    return decryptSession(raw, key);
+  }
+  /**
+   * Server-Side Helper: Generate a Set-Cookie header that expires and destroys the session cookie.
+   */
+  clearSessionCookie(options) {
+    return buildClearCookieHeader({
+      httpOnly: true,
+      secure: true,
+      sameSite: "Lax",
+      path: "/",
+      ...options
+    });
+  }
+};
+
+// src/storage.ts
+var FlitStorage = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Upload a file (Blob, File, or Buffer) to Flit Cloud Storage
+   */
+  async upload(file, fileName, options = {}) {
+    if (!file || !fileName) {
+      throw new FlitError("File and fileName are required for storage upload", "INVALID_PARAMS");
+    }
+    const formData = new FormData();
+    formData.append("file", file, fileName);
+    formData.append("appId", this.client.appId);
+    if (options.contentType) {
+      formData.append("contentType", options.contentType);
+    }
+    return this.client.request("/api/baas/storage/upload", {
+      method: "POST",
+      body: formData,
+      headers: {
+        // Leave Content-Type empty so fetch sets multipart/form-data with boundary
+      }
+    });
+  }
+  /**
+   * Generate a public URL for a stored asset
+   */
+  getPublicUrl(key) {
+    const cleanKey = key.replace(/^\/+/, "");
+    return `${this.client.endpoint}/api/baas/storage/${encodeURIComponent(this.client.appId)}/${cleanKey}`;
+  }
+};
+
+// src/client.ts
+var FlitClient = class {
+  appId;
+  apiKey;
+  endpoint;
+  timeout;
+  customHeaders;
+  customFetch;
+  debug;
+  credentials;
+  _storageAdapter;
+  // Sub-services
+  _payments;
+  _auth;
+  _storage;
+  constructor(options) {
+    if (!options || !options.appId) {
+      throw new FlitError("appId is required to initialize FlitClient", "MISSING_CONFIG");
+    }
+    this.appId = options.appId.trim();
+    this.apiKey = options.apiKey?.trim();
+    this.endpoint = (options.endpoint || "https://api.flit.site").replace(/\/+$/, "");
+    this.timeout = options.timeout || 15e3;
+    this.customHeaders = options.headers || {};
+    this.customFetch = options.fetch;
+    this.debug = !!options.debug;
+    this.credentials = options.credentials || "include";
+    this._storageAdapter = options.storage;
+    if (typeof window !== "undefined" && this.apiKey && this.apiKey.startsWith("flit_sk_")) {
+      throw new FlitError(
+        "CRITICAL SECURITY VIOLATION: Flit Secret Service Key (flit_sk_...) must NEVER be exposed in client-side browser code! Use your Public Anon Key (flit_pk_...) in frontend applications, and keep Secret Keys strictly on your server.",
+        "SECRET_KEY_EXPOSURE"
+      );
+    }
+    if (this.debug) {
+      console.log(`[Flit SDK] Initialized client for app: ${this.appId} on endpoint: ${this.endpoint}`);
+    }
+  }
+  /**
+   * Access a database collection
+   * @param name Name of the collection (e.g. 'products', 'users', 'orders')
+   */
+  collection(name) {
+    return new Collection(this, name);
+  }
+  /**
+   * Access Mobile Money payments service (Orange Money, MTN MoMo, Wave)
+   */
+  get payments() {
+    if (!this._payments) {
+      this._payments = new FlitPayments(this);
+    }
+    return this._payments;
+  }
+  /**
+   * Access Authentication service
+   */
+  get auth() {
+    if (!this._auth) {
+      this._auth = new FlitAuth(this, this._storageAdapter);
+    }
+    return this._auth;
+  }
+  /**
+   * Access Storage & File upload service
+   */
+  get storage() {
+    if (!this._storage) {
+      this._storage = new FlitStorage(this);
+    }
+    return this._storage;
+  }
+  /**
+   * Internal HTTP request transport with timeout and error handling
+   */
+  async request(path, init = {}) {
+    const cleanPath = path.startsWith("/") ? path : `/${path}`;
+    const url = `${this.endpoint}${cleanPath}`;
+    const headers = {
+      "Accept": "application/json",
+      "X-Flit-App-Id": this.appId,
+      ...this.customHeaders,
+      ...init.headers || {}
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+      headers["X-Flit-Api-Key"] = this.apiKey;
+    }
+    if (init.body && typeof init.body === "string" && !headers["Content-Type"]) {
+      headers["Content-Type"] = "application/json";
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    const fetchFn = this.customFetch || globalThis.fetch;
+    if (typeof fetchFn !== "function") {
+      clearTimeout(timer);
+      throw new FlitError(
+        "Global fetch is not available. Provide a custom fetch implementation in FlitClientOptions.",
+        "FETCH_UNAVAILABLE"
+      );
+    }
+    try {
+      if (this.debug) {
+        console.log(`[Flit SDK] ${init.method || "GET"} ${url}`);
+      }
+      const response = await fetchFn(url, {
+        credentials: this.credentials,
+        ...init,
+        headers,
+        signal: controller.signal
+      });
+      clearTimeout(timer);
+      let data;
+      const contentType = response.headers.get("content-type") || "";
+      if (contentType.includes("application/json")) {
+        data = await response.json();
+      } else {
+        const text = await response.text();
+        try {
+          data = JSON.parse(text);
+        } catch {
+          data = { text };
+        }
+      }
+      if (!response.ok) {
+        const errorMessage = data?.error || data?.message || response.statusText || "Unknown Server Error";
+        throw new FlitAPIError(
+          `[Flit API Error ${response.status}]: ${errorMessage}`,
+          response.status,
+          data?.code || "HTTP_ERROR",
+          data
+        );
+      }
+      return data;
+    } catch (err) {
+      clearTimeout(timer);
+      if (err instanceof FlitAPIError) {
+        throw err;
+      }
+      if (err.name === "AbortError") {
+        throw new FlitAPIError(
+          `Request to ${cleanPath} timed out after ${this.timeout}ms`,
+          408,
+          "TIMEOUT"
+        );
+      }
+      throw new FlitError(
+        err.message || "Failed to execute network request to Flit API",
+        "NETWORK_ERROR"
+      );
+    }
+  }
+};
+
+// src/index.ts
+function createClient(options) {
+  return new FlitClient(options);
+}
+var index_default = createClient;
+
+exports.Collection = Collection;
+exports.FlitAPIError = FlitAPIError;
+exports.FlitAuth = FlitAuth;
+exports.FlitAuthError = FlitAuthError;
+exports.FlitClient = FlitClient;
+exports.FlitError = FlitError;
+exports.FlitPaymentError = FlitPaymentError;
+exports.FlitPayments = FlitPayments;
+exports.FlitStorage = FlitStorage;
+exports.buildClearCookieHeader = buildClearCookieHeader;
+exports.buildSetCookieHeader = buildSetCookieHeader;
+exports.createClient = createClient;
+exports.decryptSession = decryptSession;
+exports.default = index_default;
+exports.encryptSession = encryptSession;
+exports.parseCookieFromHeader = parseCookieFromHeader;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map