@jupitermetalabs/face-zk-sdk 0.3.4 → 0.3.5

package/dist/FaceZkSdk.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Copyright 2026 JupiterMeta Labs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * Face+ZK SDK – Main SDK Class
+ *
+ * `FaceZkSdk` is the single entry point for initializing the SDK.
+ * Call `FaceZkSdk.init(config)` once at app startup before using any SDK features.
+ *
+ * @example – models bundled in the app (user copies assets via `npx face-zk setup --bundle`)
+ * ```ts
+ * import { FaceZkSdk } from '@jupitermetalabs/face-zk-sdk';
+ *
+ * await FaceZkSdk.init({
+ *   models: {
+ *     detection:   { module: require('./assets/face-zk/det_500m.onnx') },
+ *     recognition: { module: require('./assets/face-zk/w600k_mbf.onnx') },
+ *   },
+ * });
+ * ```
+ *
+ * @example – models downloaded from CDN on first use
+ * ```ts
+ * await FaceZkSdk.init({
+ *   models: {
+ *     detection:   { url: 'https://cdn.example.com/face-zk/det_500m.onnx' },
+ *     recognition: { url: 'https://cdn.example.com/face-zk/w600k_mbf.onnx' },
+ *   },
+ * });
+ * ```
+ */
+import type { FaceZkConfig } from "./config/types";
+type SdkInitState = "uninitialized" | "initializing" | "ready" | "error";
+export declare class FaceZkSdk {
+    /**
+     * Initialize the SDK with model sources and optional feature flags.
+     * Must be called once before using any SDK features (enrollment, verification, ZK proofs).
+     *
+     * Safe to await at app startup (in App.tsx, before rendering the root navigator).
+     */
+    static init(config: FaceZkConfig): Promise<void>;
+    /**
+     * Returns the resolved SDK config.
+     * Throws if `init()` hasn't been called yet.
+     */
+    static getConfig(): FaceZkConfig;
+    /** Returns true if `init()` has completed successfully. */
+    static isInitialized(): boolean;
+    /** Returns the current init state: 'uninitialized' | 'initializing' | 'ready' | 'error' */
+    static getState(): SdkInitState;
+    /** Returns the error from the last failed `init()` call, if any. */
+    static getInitError(): Error | null;
+    /**
+     * Reset SDK state. Useful for tests or re-initialization flows.
+     */
+    static reset(): void;
+}
+export {};

package/dist/FaceZkSdk.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Copyright 2026 JupiterMeta Labs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * Face+ZK SDK – Main SDK Class
+ *
+ * `FaceZkSdk` is the single entry point for initializing the SDK.
+ * Call `FaceZkSdk.init(config)` once at app startup before using any SDK features.
+ *
+ * @example – models bundled in the app (user copies assets via `npx face-zk setup --bundle`)
+ * ```ts
+ * import { FaceZkSdk } from '@jupitermetalabs/face-zk-sdk';
+ *
+ * await FaceZkSdk.init({
+ *   models: {
+ *     detection:   { module: require('./assets/face-zk/det_500m.onnx') },
+ *     recognition: { module: require('./assets/face-zk/w600k_mbf.onnx') },
+ *   },
+ * });
+ * ```
+ *
+ * @example – models downloaded from CDN on first use
+ * ```ts
+ * await FaceZkSdk.init({
+ *   models: {
+ *     detection:   { url: 'https://cdn.example.com/face-zk/det_500m.onnx' },
+ *     recognition: { url: 'https://cdn.example.com/face-zk/w600k_mbf.onnx' },
+ *   },
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FaceZkSdk = void 0;
+// Module-level state (singleton)
+let _state = "uninitialized";
+let _config = null;
+let _initError = null;
+class FaceZkSdk {
+    /**
+     * Initialize the SDK with model sources and optional feature flags.
+     * Must be called once before using any SDK features (enrollment, verification, ZK proofs).
+     *
+     * Safe to await at app startup (in App.tsx, before rendering the root navigator).
+     */
+    static async init(config) {
+        if (_state === "initializing") {
+            throw new Error("[FaceZkSdk] Already initializing. Avoid calling init() concurrently.");
+        }
+        if (_state === "ready") {
+            throw new Error("[FaceZkSdk] Already initialized. Call FaceZkSdk.reset() before re-initializing.");
+        }
+        _state = "initializing";
+        _initError = null;
+        try {
+            validateConfig(config);
+            _config = config;
+            _state = "ready";
+        }
+        catch (err) {
+            _state = "error";
+            _initError = err instanceof Error ? err : new Error(String(err));
+            throw _initError;
+        }
+    }
+    /**
+     * Returns the resolved SDK config.
+     * Throws if `init()` hasn't been called yet.
+     */
+    static getConfig() {
+        if (_state !== "ready" || !_config) {
+            throw new Error("[FaceZkSdk] Not initialized. Call FaceZkSdk.init(config) before using SDK features.");
+        }
+        return _config;
+    }
+    /** Returns true if `init()` has completed successfully. */
+    static isInitialized() {
+        return _state === "ready";
+    }
+    /** Returns the current init state: 'uninitialized' | 'initializing' | 'ready' | 'error' */
+    static getState() {
+        return _state;
+    }
+    /** Returns the error from the last failed `init()` call, if any. */
+    static getInitError() {
+        return _initError;
+    }
+    /**
+     * Reset SDK state. Useful for tests or re-initialization flows.
+     */
+    static reset() {
+        _state = "uninitialized";
+        _config = null;
+        _initError = null;
+    }
+}
+exports.FaceZkSdk = FaceZkSdk;
+// ============================================================================
+// Internal validation
+// ============================================================================
+function validateConfig(config) {
+    if (!config || typeof config !== "object") {
+        throw new Error("[FaceZkSdk] config must be an object.");
+    }
+    if (!config.models || typeof config.models !== "object") {
+        throw new Error("[FaceZkSdk] config.models is required.");
+    }
+    if (!config.models.detection) {
+        throw new Error("[FaceZkSdk] config.models.detection is required. " +
+            "Provide a { module }, { url }, or { localUri }.");
+    }
+    if (!config.models.recognition) {
+        throw new Error("[FaceZkSdk] config.models.recognition is required. " +
+            "Provide a { module }, { url }, or { localUri }.");
+    }
+    // Each provided ModelSource must have at least one resolvable field
+    const modelEntries = Object.entries(config.models);
+    for (const [key, source] of modelEntries) {
+        if (!source)
+            continue;
+        if (!source.module && !source.url && !source.localUri) {
+            throw new Error(`[FaceZkSdk] config.models.${key} must have at least one of: module, url, localUri.`);
+        }
+    }
+}