@disconnectme/lightbox-sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,181 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  LightboxClient: () => LightboxClient,
+  LightboxError: () => LightboxError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var LightboxError = class _LightboxError extends Error {
+  constructor(message, code, type, requestId, param) {
+    super(message);
+    this.code = code;
+    this.type = type;
+    this.requestId = requestId;
+    this.param = param;
+    this.name = "LightboxError";
+  }
+  static fromAPIError(error) {
+    return new _LightboxError(
+      error.error.message,
+      error.error.code,
+      error.error.type,
+      error.error.request_id,
+      error.error.param
+    );
+  }
+};
+var LightboxClient = class {
+  baseUrl;
+  apiKey;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl ?? "https://api.datafin.ai";
+  }
+  async request(path, params) {
+    const url = new URL(path, this.baseUrl);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value === void 0 || value === null) continue;
+        if (Array.isArray(value)) {
+          url.searchParams.set(key, value.join(","));
+        } else {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    const response = await fetch(url.toString(), {
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json"
+      }
+    });
+    const data = await response.json();
+    if (!response.ok) {
+      throw LightboxError.fromAPIError(data);
+    }
+    return data;
+  }
+  /**
+   * File-related API methods
+   */
+  files = {
+    /**
+     * Search for files across apps by extension, filename, bundle, etc.
+     * Requires at least one of `extensions` or `filenames`.
+     */
+    search: (params) => {
+      return this.request("/v1/files/search", params);
+    },
+    /**
+     * Get all occurrences of a file by its hash.
+     * Returns the apps containing this file and download URLs.
+     */
+    get: (hash, params) => {
+      return this.request(`/v1/files/${hash}`, params);
+    }
+  };
+  /**
+   * App-related API methods (iOS apps)
+   */
+  apps = {
+    /**
+     * Search for iOS apps by framework, permission, genre, developer, name, or bundle.
+     * Requires at least one filter parameter.
+     */
+    search: (params) => {
+      return this.request("/v1/apps/ios/search", params);
+    },
+    /**
+     * Get detailed profile for a specific app bundle.
+     * Use `version` param to get a specific version, defaults to latest.
+     * Use `include` to specify which fields to include (frameworks, permissions, privacy, urls, files, all).
+     */
+    get: (bundle, params) => {
+      const queryParams = {};
+      if (params?.version) queryParams.version = params.version;
+      if (params?.include) queryParams.include = params.include.join(",");
+      return this.request(
+        `/v1/apps/ios/${encodeURIComponent(bundle)}`,
+        queryParams
+      );
+    },
+    /**
+     * List all available versions for an app bundle.
+     */
+    versions: (bundle, params) => {
+      return this.request(
+        `/v1/apps/ios/${encodeURIComponent(bundle)}/versions`,
+        params
+      );
+    },
+    /**
+     * List files within an app, optionally filtered by extension, name, path, or size.
+     */
+    files: (bundle, params) => {
+      return this.request(
+        `/v1/apps/ios/${encodeURIComponent(bundle)}/files`,
+        params
+      );
+    },
+    /**
+     * Metadata endpoints for discovering available filter values
+     */
+    metadata: {
+      /**
+       * Get all available App Store genres with app counts.
+       * Returns a fixed set of 26 genres.
+       */
+      genres: () => {
+        return this.request("/v1/apps/ios/metadata/genres");
+      },
+      /**
+       * Get available frameworks with app counts.
+       * Supports pagination and search.
+       * @param params.search - Filter by framework name (case-insensitive contains)
+       * @param params.sort - Sort by 'popularity' (default) or 'name'
+       * @param params.limit - Results per page (default 100, max 1000)
+       * @param params.offset - Pagination offset
+       */
+      frameworks: (params) => {
+        return this.request("/v1/apps/ios/metadata/frameworks", params);
+      },
+      /**
+       * Get available permissions (iOS entitlements) with app counts.
+       * Supports pagination and search.
+       * @param params.search - Filter by permission key (case-insensitive contains)
+       * @param params.sort - Sort by 'popularity' (default) or 'name'
+       * @param params.limit - Results per page (default 100, max 1000)
+       * @param params.offset - Pagination offset
+       */
+      permissions: (params) => {
+        return this.request("/v1/apps/ios/metadata/permissions", params);
+      }
+    }
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LightboxClient,
+  LightboxError
+});

package/dist/index.d.cts

@@ -0,0 +1,307 @@
+interface APIMetadata {
+    api_version: string;
+    query_time_ms: number;
+    data_sources: string[];
+    data_freshness: string | null;
+    credits_used: number;
+    request_id: string;
+}
+interface Pagination {
+    limit: number;
+    offset: number;
+    returned: number;
+    has_more: boolean;
+    next_offset?: number;
+}
+interface APIResponse<T> {
+    _metadata: APIMetadata;
+    query: Record<string, unknown>;
+    data: T;
+    pagination: Pagination | null;
+}
+interface APIError {
+    error: {
+        code: string;
+        message: string;
+        type: string;
+        param?: string;
+        request_id: string;
+    };
+}
+interface FileSearchResult {
+    bundle: string;
+    version: string;
+    file_name: string;
+    file_extension: string;
+    file_hash: string;
+    file_path: string | null;
+    file_size_bytes: number;
+    download_url: string | null;
+    expires_at: string | null;
+}
+interface FileHashResult {
+    bundle: string;
+    version: string;
+    type: string;
+    name: string;
+    created_at: string;
+    file_path: string | null;
+    file_size: number;
+    download_url: string | null;
+    expires_at: string | null;
+}
+interface FileSearchData {
+    type: "file_collection";
+    summary: {
+        returned: number;
+    };
+    files: FileSearchResult[];
+}
+interface FileHashData {
+    type: "file_occurrences";
+    file: {
+        file_hash: string;
+        total_occurrences: number;
+        app_count: number;
+    } | null;
+    apps: FileHashResult[];
+}
+interface AppSummary {
+    bundle: string;
+    version: string;
+    name: string;
+    type: string;
+    genre: string | null;
+    developer: string | null;
+    review_count: number | null;
+    rating: number | null;
+    app_store_url: string | null;
+    frameworks: string[];
+    permissions: string[];
+    created_at: string;
+}
+interface AppProfile {
+    bundle: string;
+    version: string;
+    name: string;
+    type: string;
+    genre: string | null;
+    developer: string | null;
+    review_count: number | null;
+    rating: number | null;
+    app_store_url: string | null;
+    created_at: string;
+    frameworks?: string[];
+    permissions?: string[];
+    privacy?: unknown[];
+    urls?: unknown[];
+    files?: unknown[];
+}
+interface AppVersion {
+    version: string;
+    created_at: string;
+    review_count: number | null;
+    rating: number | null;
+    genre: string | null;
+    developer: string | null;
+}
+interface AppFile {
+    bundle: string;
+    version: string;
+    file_name: string;
+    file_extension: string;
+    file_hash: string;
+    file_path: string | null;
+    file_size_bytes: number;
+    download_url: string | null;
+    expires_at: string | null;
+}
+interface AppSearchData {
+    type: "app_collection";
+    summary: {
+        total_matches: number;
+        returned: number;
+    };
+    apps: AppSummary[];
+}
+interface AppProfileData {
+    type: "app_profile";
+    app: AppProfile;
+}
+interface AppVersionsData {
+    type: "version_collection";
+    versions: AppVersion[];
+}
+interface AppFilesData {
+    type: "file_collection";
+    app: {
+        bundle: string;
+        version: string;
+    };
+    summary: {
+        returned: number;
+    };
+    files: AppFile[];
+}
+interface PaginationParams {
+    limit?: number;
+    offset?: number;
+}
+interface FileSearchParams extends PaginationParams {
+    extensions?: string[];
+    filenames?: string[];
+    bundles?: string[];
+    exclude_bundles?: string[];
+    exclude_hashes?: string[];
+    bundle_prefix?: string;
+    min_size?: number;
+    max_size?: number;
+}
+interface AppSearchParams extends PaginationParams {
+    framework?: string;
+    permission?: string;
+    genre?: string;
+    developer?: string;
+    name?: string;
+    bundle?: string;
+}
+interface AppGetParams {
+    version?: string;
+    include?: string[];
+}
+interface AppFilesParams extends PaginationParams {
+    version?: string;
+    extension?: string;
+    name?: string;
+    path?: string;
+    min_size?: number;
+    max_size?: number;
+}
+interface GenreItem {
+    name: string;
+    app_count: number;
+}
+interface FrameworkItem {
+    name: string;
+    app_count: number;
+}
+interface PermissionItem {
+    key: string;
+    app_count: number;
+}
+interface GenreListData {
+    type: "genre_list";
+    total: number;
+    genres: GenreItem[];
+}
+interface FrameworkListData {
+    type: "framework_list";
+    total: number;
+    frameworks: FrameworkItem[];
+}
+interface PermissionListData {
+    type: "permission_list";
+    total: number;
+    permissions: PermissionItem[];
+}
+interface MetadataSearchParams extends PaginationParams {
+    search?: string;
+    sort?: "popularity" | "name";
+}
+type FileSearchResponse = APIResponse<FileSearchData>;
+type FileHashResponse = APIResponse<FileHashData>;
+type AppSearchResponse = APIResponse<AppSearchData>;
+type AppProfileResponse = APIResponse<AppProfileData>;
+type AppVersionsResponse = APIResponse<AppVersionsData>;
+type AppFilesResponse = APIResponse<AppFilesData>;
+type GenreListResponse = APIResponse<GenreListData>;
+type FrameworkListResponse = APIResponse<FrameworkListData>;
+type PermissionListResponse = APIResponse<PermissionListData>;
+
+interface LightboxClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+declare class LightboxError extends Error {
+    code: string;
+    type: string;
+    requestId: string;
+    param?: string | undefined;
+    constructor(message: string, code: string, type: string, requestId: string, param?: string | undefined);
+    static fromAPIError(error: APIError): LightboxError;
+}
+declare class LightboxClient {
+    private baseUrl;
+    private apiKey;
+    constructor(config: LightboxClientConfig);
+    private request;
+    /**
+     * File-related API methods
+     */
+    files: {
+        /**
+         * Search for files across apps by extension, filename, bundle, etc.
+         * Requires at least one of `extensions` or `filenames`.
+         */
+        search: (params: FileSearchParams) => Promise<FileSearchResponse>;
+        /**
+         * Get all occurrences of a file by its hash.
+         * Returns the apps containing this file and download URLs.
+         */
+        get: (hash: string, params?: PaginationParams) => Promise<FileHashResponse>;
+    };
+    /**
+     * App-related API methods (iOS apps)
+     */
+    apps: {
+        /**
+         * Search for iOS apps by framework, permission, genre, developer, name, or bundle.
+         * Requires at least one filter parameter.
+         */
+        search: (params: AppSearchParams) => Promise<AppSearchResponse>;
+        /**
+         * Get detailed profile for a specific app bundle.
+         * Use `version` param to get a specific version, defaults to latest.
+         * Use `include` to specify which fields to include (frameworks, permissions, privacy, urls, files, all).
+         */
+        get: (bundle: string, params?: AppGetParams) => Promise<AppProfileResponse>;
+        /**
+         * List all available versions for an app bundle.
+         */
+        versions: (bundle: string, params?: PaginationParams) => Promise<AppVersionsResponse>;
+        /**
+         * List files within an app, optionally filtered by extension, name, path, or size.
+         */
+        files: (bundle: string, params?: AppFilesParams) => Promise<AppFilesResponse>;
+        /**
+         * Metadata endpoints for discovering available filter values
+         */
+        metadata: {
+            /**
+             * Get all available App Store genres with app counts.
+             * Returns a fixed set of 26 genres.
+             */
+            genres: () => Promise<GenreListResponse>;
+            /**
+             * Get available frameworks with app counts.
+             * Supports pagination and search.
+             * @param params.search - Filter by framework name (case-insensitive contains)
+             * @param params.sort - Sort by 'popularity' (default) or 'name'
+             * @param params.limit - Results per page (default 100, max 1000)
+             * @param params.offset - Pagination offset
+             */
+            frameworks: (params?: MetadataSearchParams) => Promise<FrameworkListResponse>;
+            /**
+             * Get available permissions (iOS entitlements) with app counts.
+             * Supports pagination and search.
+             * @param params.search - Filter by permission key (case-insensitive contains)
+             * @param params.sort - Sort by 'popularity' (default) or 'name'
+             * @param params.limit - Results per page (default 100, max 1000)
+             * @param params.offset - Pagination offset
+             */
+            permissions: (params?: MetadataSearchParams) => Promise<PermissionListResponse>;
+        };
+    };
+}
+
+export { type APIError, type APIMetadata, type APIResponse, type AppFile, type AppFilesData, type AppFilesParams, type AppFilesResponse, type AppGetParams, type AppProfile, type AppProfileData, type AppProfileResponse, type AppSearchData, type AppSearchParams, type AppSearchResponse, type AppSummary, type AppVersion, type AppVersionsData, type AppVersionsResponse, type FileHashData, type FileHashResponse, type FileHashResult, type FileSearchData, type FileSearchParams, type FileSearchResponse, type FileSearchResult, type FrameworkItem, type FrameworkListData, type FrameworkListResponse, type GenreItem, type GenreListData, type GenreListResponse, LightboxClient, type LightboxClientConfig, LightboxError, type MetadataSearchParams, type Pagination, type PaginationParams, type PermissionItem, type PermissionListData, type PermissionListResponse };

package/dist/index.d.ts

@@ -0,0 +1,307 @@
+interface APIMetadata {
+    api_version: string;
+    query_time_ms: number;
+    data_sources: string[];
+    data_freshness: string | null;
+    credits_used: number;
+    request_id: string;
+}
+interface Pagination {
+    limit: number;
+    offset: number;
+    returned: number;
+    has_more: boolean;
+    next_offset?: number;
+}
+interface APIResponse<T> {
+    _metadata: APIMetadata;
+    query: Record<string, unknown>;
+    data: T;
+    pagination: Pagination | null;
+}
+interface APIError {
+    error: {
+        code: string;
+        message: string;
+        type: string;
+        param?: string;
+        request_id: string;
+    };
+}
+interface FileSearchResult {
+    bundle: string;
+    version: string;
+    file_name: string;
+    file_extension: string;
+    file_hash: string;
+    file_path: string | null;
+    file_size_bytes: number;
+    download_url: string | null;
+    expires_at: string | null;
+}
+interface FileHashResult {
+    bundle: string;
+    version: string;
+    type: string;
+    name: string;
+    created_at: string;
+    file_path: string | null;
+    file_size: number;
+    download_url: string | null;
+    expires_at: string | null;
+}
+interface FileSearchData {
+    type: "file_collection";
+    summary: {
+        returned: number;
+    };
+    files: FileSearchResult[];
+}
+interface FileHashData {
+    type: "file_occurrences";
+    file: {
+        file_hash: string;
+        total_occurrences: number;
+        app_count: number;
+    } | null;
+    apps: FileHashResult[];
+}
+interface AppSummary {
+    bundle: string;
+    version: string;
+    name: string;
+    type: string;
+    genre: string | null;
+    developer: string | null;
+    review_count: number | null;
+    rating: number | null;
+    app_store_url: string | null;
+    frameworks: string[];
+    permissions: string[];
+    created_at: string;
+}
+interface AppProfile {
+    bundle: string;
+    version: string;
+    name: string;
+    type: string;
+    genre: string | null;
+    developer: string | null;
+    review_count: number | null;
+    rating: number | null;
+    app_store_url: string | null;
+    created_at: string;
+    frameworks?: string[];
+    permissions?: string[];
+    privacy?: unknown[];
+    urls?: unknown[];
+    files?: unknown[];
+}
+interface AppVersion {
+    version: string;
+    created_at: string;
+    review_count: number | null;
+    rating: number | null;
+    genre: string | null;
+    developer: string | null;
+}
+interface AppFile {
+    bundle: string;
+    version: string;
+    file_name: string;
+    file_extension: string;
+    file_hash: string;
+    file_path: string | null;
+    file_size_bytes: number;
+    download_url: string | null;
+    expires_at: string | null;
+}
+interface AppSearchData {
+    type: "app_collection";
+    summary: {
+        total_matches: number;
+        returned: number;
+    };
+    apps: AppSummary[];
+}
+interface AppProfileData {
+    type: "app_profile";
+    app: AppProfile;
+}
+interface AppVersionsData {
+    type: "version_collection";
+    versions: AppVersion[];
+}
+interface AppFilesData {
+    type: "file_collection";
+    app: {
+        bundle: string;
+        version: string;
+    };
+    summary: {
+        returned: number;
+    };
+    files: AppFile[];
+}
+interface PaginationParams {
+    limit?: number;
+    offset?: number;
+}
+interface FileSearchParams extends PaginationParams {
+    extensions?: string[];
+    filenames?: string[];
+    bundles?: string[];
+    exclude_bundles?: string[];
+    exclude_hashes?: string[];
+    bundle_prefix?: string;
+    min_size?: number;
+    max_size?: number;
+}
+interface AppSearchParams extends PaginationParams {
+    framework?: string;
+    permission?: string;
+    genre?: string;
+    developer?: string;
+    name?: string;
+    bundle?: string;
+}
+interface AppGetParams {
+    version?: string;
+    include?: string[];
+}
+interface AppFilesParams extends PaginationParams {
+    version?: string;
+    extension?: string;
+    name?: string;
+    path?: string;
+    min_size?: number;
+    max_size?: number;
+}
+interface GenreItem {
+    name: string;
+    app_count: number;
+}
+interface FrameworkItem {
+    name: string;
+    app_count: number;
+}
+interface PermissionItem {
+    key: string;
+    app_count: number;
+}
+interface GenreListData {
+    type: "genre_list";
+    total: number;
+    genres: GenreItem[];
+}
+interface FrameworkListData {
+    type: "framework_list";
+    total: number;
+    frameworks: FrameworkItem[];
+}
+interface PermissionListData {
+    type: "permission_list";
+    total: number;
+    permissions: PermissionItem[];
+}
+interface MetadataSearchParams extends PaginationParams {
+    search?: string;
+    sort?: "popularity" | "name";
+}
+type FileSearchResponse = APIResponse<FileSearchData>;
+type FileHashResponse = APIResponse<FileHashData>;
+type AppSearchResponse = APIResponse<AppSearchData>;
+type AppProfileResponse = APIResponse<AppProfileData>;
+type AppVersionsResponse = APIResponse<AppVersionsData>;
+type AppFilesResponse = APIResponse<AppFilesData>;
+type GenreListResponse = APIResponse<GenreListData>;
+type FrameworkListResponse = APIResponse<FrameworkListData>;
+type PermissionListResponse = APIResponse<PermissionListData>;
+
+interface LightboxClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+declare class LightboxError extends Error {
+    code: string;
+    type: string;
+    requestId: string;
+    param?: string | undefined;
+    constructor(message: string, code: string, type: string, requestId: string, param?: string | undefined);
+    static fromAPIError(error: APIError): LightboxError;
+}
+declare class LightboxClient {
+    private baseUrl;
+    private apiKey;
+    constructor(config: LightboxClientConfig);
+    private request;
+    /**
+     * File-related API methods
+     */
+    files: {
+        /**
+         * Search for files across apps by extension, filename, bundle, etc.
+         * Requires at least one of `extensions` or `filenames`.
+         */
+        search: (params: FileSearchParams) => Promise<FileSearchResponse>;
+        /**
+         * Get all occurrences of a file by its hash.
+         * Returns the apps containing this file and download URLs.
+         */
+        get: (hash: string, params?: PaginationParams) => Promise<FileHashResponse>;
+    };
+    /**
+     * App-related API methods (iOS apps)
+     */
+    apps: {
+        /**
+         * Search for iOS apps by framework, permission, genre, developer, name, or bundle.
+         * Requires at least one filter parameter.
+         */
+        search: (params: AppSearchParams) => Promise<AppSearchResponse>;
+        /**
+         * Get detailed profile for a specific app bundle.
+         * Use `version` param to get a specific version, defaults to latest.
+         * Use `include` to specify which fields to include (frameworks, permissions, privacy, urls, files, all).
+         */
+        get: (bundle: string, params?: AppGetParams) => Promise<AppProfileResponse>;
+        /**
+         * List all available versions for an app bundle.
+         */
+        versions: (bundle: string, params?: PaginationParams) => Promise<AppVersionsResponse>;
+        /**
+         * List files within an app, optionally filtered by extension, name, path, or size.
+         */
+        files: (bundle: string, params?: AppFilesParams) => Promise<AppFilesResponse>;
+        /**
+         * Metadata endpoints for discovering available filter values
+         */
+        metadata: {
+            /**
+             * Get all available App Store genres with app counts.
+             * Returns a fixed set of 26 genres.
+             */
+            genres: () => Promise<GenreListResponse>;
+            /**
+             * Get available frameworks with app counts.
+             * Supports pagination and search.
+             * @param params.search - Filter by framework name (case-insensitive contains)
+             * @param params.sort - Sort by 'popularity' (default) or 'name'
+             * @param params.limit - Results per page (default 100, max 1000)
+             * @param params.offset - Pagination offset
+             */
+            frameworks: (params?: MetadataSearchParams) => Promise<FrameworkListResponse>;
+            /**
+             * Get available permissions (iOS entitlements) with app counts.
+             * Supports pagination and search.
+             * @param params.search - Filter by permission key (case-insensitive contains)
+             * @param params.sort - Sort by 'popularity' (default) or 'name'
+             * @param params.limit - Results per page (default 100, max 1000)
+             * @param params.offset - Pagination offset
+             */
+            permissions: (params?: MetadataSearchParams) => Promise<PermissionListResponse>;
+        };
+    };
+}
+
+export { type APIError, type APIMetadata, type APIResponse, type AppFile, type AppFilesData, type AppFilesParams, type AppFilesResponse, type AppGetParams, type AppProfile, type AppProfileData, type AppProfileResponse, type AppSearchData, type AppSearchParams, type AppSearchResponse, type AppSummary, type AppVersion, type AppVersionsData, type AppVersionsResponse, type FileHashData, type FileHashResponse, type FileHashResult, type FileSearchData, type FileSearchParams, type FileSearchResponse, type FileSearchResult, type FrameworkItem, type FrameworkListData, type FrameworkListResponse, type GenreItem, type GenreListData, type GenreListResponse, LightboxClient, type LightboxClientConfig, LightboxError, type MetadataSearchParams, type Pagination, type PaginationParams, type PermissionItem, type PermissionListData, type PermissionListResponse };

package/dist/index.js

@@ -0,0 +1,153 @@
+// src/client.ts
+var LightboxError = class _LightboxError extends Error {
+  constructor(message, code, type, requestId, param) {
+    super(message);
+    this.code = code;
+    this.type = type;
+    this.requestId = requestId;
+    this.param = param;
+    this.name = "LightboxError";
+  }
+  static fromAPIError(error) {
+    return new _LightboxError(
+      error.error.message,
+      error.error.code,
+      error.error.type,
+      error.error.request_id,
+      error.error.param
+    );
+  }
+};
+var LightboxClient = class {
+  baseUrl;
+  apiKey;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl ?? "https://api.datafin.ai";
+  }
+  async request(path, params) {
+    const url = new URL(path, this.baseUrl);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value === void 0 || value === null) continue;
+        if (Array.isArray(value)) {
+          url.searchParams.set(key, value.join(","));
+        } else {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    const response = await fetch(url.toString(), {
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json"
+      }
+    });
+    const data = await response.json();
+    if (!response.ok) {
+      throw LightboxError.fromAPIError(data);
+    }
+    return data;
+  }
+  /**
+   * File-related API methods
+   */
+  files = {
+    /**
+     * Search for files across apps by extension, filename, bundle, etc.
+     * Requires at least one of `extensions` or `filenames`.
+     */
+    search: (params) => {
+      return this.request("/v1/files/search", params);
+    },
+    /**
+     * Get all occurrences of a file by its hash.
+     * Returns the apps containing this file and download URLs.
+     */
+    get: (hash, params) => {
+      return this.request(`/v1/files/${hash}`, params);
+    }
+  };
+  /**
+   * App-related API methods (iOS apps)
+   */
+  apps = {
+    /**
+     * Search for iOS apps by framework, permission, genre, developer, name, or bundle.
+     * Requires at least one filter parameter.
+     */
+    search: (params) => {
+      return this.request("/v1/apps/ios/search", params);
+    },
+    /**
+     * Get detailed profile for a specific app bundle.
+     * Use `version` param to get a specific version, defaults to latest.
+     * Use `include` to specify which fields to include (frameworks, permissions, privacy, urls, files, all).
+     */
+    get: (bundle, params) => {
+      const queryParams = {};
+      if (params?.version) queryParams.version = params.version;
+      if (params?.include) queryParams.include = params.include.join(",");
+      return this.request(
+        `/v1/apps/ios/${encodeURIComponent(bundle)}`,
+        queryParams
+      );
+    },
+    /**
+     * List all available versions for an app bundle.
+     */
+    versions: (bundle, params) => {
+      return this.request(
+        `/v1/apps/ios/${encodeURIComponent(bundle)}/versions`,
+        params
+      );
+    },
+    /**
+     * List files within an app, optionally filtered by extension, name, path, or size.
+     */
+    files: (bundle, params) => {
+      return this.request(
+        `/v1/apps/ios/${encodeURIComponent(bundle)}/files`,
+        params
+      );
+    },
+    /**
+     * Metadata endpoints for discovering available filter values
+     */
+    metadata: {
+      /**
+       * Get all available App Store genres with app counts.
+       * Returns a fixed set of 26 genres.
+       */
+      genres: () => {
+        return this.request("/v1/apps/ios/metadata/genres");
+      },
+      /**
+       * Get available frameworks with app counts.
+       * Supports pagination and search.
+       * @param params.search - Filter by framework name (case-insensitive contains)
+       * @param params.sort - Sort by 'popularity' (default) or 'name'
+       * @param params.limit - Results per page (default 100, max 1000)
+       * @param params.offset - Pagination offset
+       */
+      frameworks: (params) => {
+        return this.request("/v1/apps/ios/metadata/frameworks", params);
+      },
+      /**
+       * Get available permissions (iOS entitlements) with app counts.
+       * Supports pagination and search.
+       * @param params.search - Filter by permission key (case-insensitive contains)
+       * @param params.sort - Sort by 'popularity' (default) or 'name'
+       * @param params.limit - Results per page (default 100, max 1000)
+       * @param params.offset - Pagination offset
+       */
+      permissions: (params) => {
+        return this.request("/v1/apps/ios/metadata/permissions", params);
+      }
+    }
+  };
+};
+export {
+  LightboxClient,
+  LightboxError
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@disconnectme/lightbox-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the Lightbox Data API by Disconnect",
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "keywords": [
+    "lightbox",
+    "api",
+    "sdk",
+    "ios",
+    "apps"
+  ],
+  "license": "MIT"
+}