@harkenapp/sdk-react-native 0.0.1-alpha.1

package/dist/utils/uuid.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateUUID = generateUUID;
+/**
+ * Generate a RFC4122 version 4 UUID.
+ *
+ * Uses crypto.getRandomValues when available (React Native),
+ * falls back to Math.random for older environments.
+ *
+ * @returns A random UUID string in the format xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+ */
+function generateUUID() {
+    // Use crypto.getRandomValues if available (React Native has this)
+    if (typeof crypto !== 'undefined' &&
+        typeof crypto.getRandomValues === 'function') {
+        return generateUUIDCrypto();
+    }
+    // Fallback to Math.random-based generation
+    return generateUUIDFallback();
+}
+/**
+ * Generate UUID using crypto.getRandomValues
+ */
+function generateUUIDCrypto() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    // Set version (4) and variant (RFC4122)
+    bytes[6] = (bytes[6] & 0x0f) | 0x40; // Version 4
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // Variant RFC4122
+    return formatUUID(bytes);
+}
+/**
+ * Generate UUID using Math.random (fallback)
+ */
+function generateUUIDFallback() {
+    const bytes = new Uint8Array(16);
+    for (let i = 0; i < 16; i++) {
+        bytes[i] = Math.floor(Math.random() * 256);
+    }
+    // Set version (4) and variant (RFC4122)
+    bytes[6] = (bytes[6] & 0x0f) | 0x40; // Version 4
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // Variant RFC4122
+    return formatUUID(bytes);
+}
+/**
+ * Format bytes as UUID string
+ */
+function formatUUID(bytes) {
+    const hex = Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+    return [
+        hex.slice(0, 8),
+        hex.slice(8, 12),
+        hex.slice(12, 16),
+        hex.slice(16, 20),
+        hex.slice(20, 32),
+    ].join('-');
+}
+//# sourceMappingURL=uuid.js.map

package/dist/utils/uuid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.js","sourceRoot":"","sources":["../../src/utils/uuid.ts"],"names":[],"mappings":";;AAkBA,oCAWC;AAnBD;;;;;;;GAOG;AACH,SAAgB,YAAY;IAC1B,kEAAkE;IAClE,IACE,OAAO,MAAM,KAAK,WAAW;QAC7B,OAAO,MAAM,CAAC,eAAe,KAAK,UAAU,EAC5C,CAAC;QACD,OAAO,kBAAkB,EAAE,CAAC;IAC9B,CAAC;IAED,2CAA2C;IAC3C,OAAO,oBAAoB,EAAE,CAAC;AAChC,CAAC;AAED;;GAEG;AACH,SAAS,kBAAkB;IACzB,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IACjC,MAAO,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAE/B,wCAAwC;IACxC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,YAAY;IAClD,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,kBAAkB;IAExD,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,SAAS,oBAAoB;IAC3B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC;IAC7C,CAAC;IAED,wCAAwC;IACxC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,YAAY;IAClD,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,kBAAkB;IAExD,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,SAAS,UAAU,CAAC,KAAiB;IACnC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;SAC1B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SAC3C,IAAI,CAAC,EAAE,CAAC,CAAC;IAEZ,OAAO;QACL,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;QACf,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;QAChB,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC;QACjB,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC;QACjB,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC;KAClB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC"}

package/package.json

@@ -0,0 +1,124 @@
+{
+  "name": "@harkenapp/sdk-react-native",
+  "version": "0.0.1-alpha.1",
+  "description": "Harken React Native / Expo SDK for in-app feedback",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "react-native": "./src/index.ts",
+  "source": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-native": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./attachments": {
+      "types": "./dist/attachments/index.d.ts",
+      "react-native": "./src/attachments/index.ts",
+      "import": "./dist/attachments/index.js",
+      "default": "./dist/attachments/index.js"
+    },
+    "./theme": {
+      "types": "./dist/theme/index.d.ts",
+      "react-native": "./src/theme/index.ts",
+      "import": "./dist/theme/index.js",
+      "default": "./dist/theme/index.js"
+    },
+    "./app.plugin.js": "./app.plugin.js",
+    "./app.plugin": "./app.plugin.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "app.plugin.js",
+    "app.plugin.cjs"
+  ],
+  "scripts": {
+    "generate": "openapi-typescript openapi.yaml -o src/types/openapi.ts",
+    "build": "pnpm run generate && tsc",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "pnpm run clean && pnpm run build"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "feedback",
+    "sdk",
+    "mobile",
+    "harken"
+  ],
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/harken-app/harken.git",
+    "directory": "packages/sdk-react-native"
+  },
+  "bugs": {
+    "url": "https://github.com/harken-app/harken/issues"
+  },
+  "homepage": "https://github.com/harken-app/harken#readme",
+  "sideEffects": false,
+  "expo": {
+    "configPlugin": "./app.plugin.cjs"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.72.0",
+    "react-native-safe-area-context": ">=4.0.0",
+    "expo": ">=54.0.0 <55.0.0",
+    "expo-secure-store": ">=13.0.0",
+    "expo-file-system": ">=19.0.0",
+    "expo-image-picker": ">=15.0.0",
+    "expo-document-picker": ">=12.0.0",
+    "@react-native-async-storage/async-storage": ">=1.21.0",
+    "@react-native-community/netinfo": ">=11.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-native": {
+      "optional": false
+    },
+    "expo": {
+      "optional": true
+    },
+    "expo-secure-store": {
+      "optional": true
+    },
+    "expo-file-system": {
+      "optional": true
+    },
+    "expo-image-picker": {
+      "optional": true
+    },
+    "expo-document-picker": {
+      "optional": true
+    },
+    "@react-native-async-storage/async-storage": {
+      "optional": true
+    },
+    "@react-native-community/netinfo": {
+      "optional": true
+    },
+    "react-native-safe-area-context": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "openapi-typescript": "^7.4.4",
+    "@react-native-async-storage/async-storage": "^2.1.0",
+    "@react-native-community/netinfo": "^11.4.1",
+    "@types/react": "^19.1.0",
+    "expo-document-picker": "^14.0.0",
+    "expo-file-system": "^19.0.0",
+    "expo-image-picker": "^17.0.0",
+    "react": "^19.1.0",
+    "react-native": "^0.81.5",
+    "react-native-safe-area-context": "^5.0.0",
+    "typescript": "^5.9.0"
+  }
+}

package/src/@types/expo-file-system-legacy.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Type declarations for expo-file-system/legacy subpath.
+ *
+ * In expo-file-system v19 (SDK 54), the legacy API containing
+ * createUploadTask() was moved to a separate subpath.
+ *
+ * This declaration enables TypeScript to resolve the import.
+ */
+declare module 'expo-file-system/legacy' {
+  // Re-export types from the build output
+  export * from 'expo-file-system/build/legacy/FileSystem';
+  export * from 'expo-file-system/build/legacy/FileSystem.types';
+}

package/src/api/client.ts

@@ -0,0 +1,250 @@
+import type { components } from '../types/index.js';
+import { HarkenApiError, HarkenNetworkError } from './errors';
+import { withRetry } from './retry';
+import type { RetryConfig } from './retry';
+
+// Re-export types from contracts for convenience
+type FeedbackSubmission = components['schemas']['FeedbackSubmission'];
+type FeedbackSubmissionResponse = components['schemas']['FeedbackSubmissionResponse'];
+type ErrorResponse = components['schemas']['ErrorResponse'];
+
+// Attachment types
+type AttachmentPresignRequest = components['schemas']['AttachmentPresignRequest'];
+type AttachmentPresignResponse = components['schemas']['AttachmentPresignResponse'];
+type AttachmentConfirmRequest = components['schemas']['AttachmentConfirmRequest'];
+type AttachmentStatusResponse = components['schemas']['AttachmentStatusResponse'];
+
+const DEFAULT_API_BASE_URL = 'https://api.harken.app';
+
+export interface HarkenClientConfig {
+  /** Publishable API key */
+  publishableKey: string;
+  /** Optional user token for verified identity */
+  userToken?: string;
+  /** Base URL for API (defaults to production) */
+  baseUrl?: string;
+  /** Retry configuration */
+  retry?: Partial<RetryConfig>;
+  /** Request timeout in ms (default: 30000) */
+  timeout?: number;
+}
+
+/**
+ * Low-level API client for Harken.
+ */
+export class HarkenClient {
+  private readonly config: Required<
+    Pick<HarkenClientConfig, 'publishableKey' | 'baseUrl' | 'timeout'>
+  > &
+    Pick<HarkenClientConfig, 'userToken' | 'retry'>;
+
+  constructor(config: HarkenClientConfig) {
+    this.config = {
+      publishableKey: config.publishableKey,
+      userToken: config.userToken,
+      baseUrl: config.baseUrl ?? DEFAULT_API_BASE_URL,
+      retry: config.retry,
+      timeout: config.timeout ?? 30000,
+    };
+  }
+
+  /**
+   * Submit feedback to the API.
+   */
+  async submitFeedback(
+    submission: FeedbackSubmission
+  ): Promise<FeedbackSubmissionResponse> {
+    return withRetry(
+      () => this.request<FeedbackSubmissionResponse>('/v1/feedback', {
+        method: 'POST',
+        body: JSON.stringify(submission),
+      }),
+      this.config.retry
+    );
+  }
+
+  /**
+   * Create a presigned URL for attachment upload.
+   */
+  async createAttachmentUpload(
+    request: AttachmentPresignRequest
+  ): Promise<AttachmentPresignResponse> {
+    return withRetry(
+      () =>
+        this.request<AttachmentPresignResponse>(
+          '/v1/feedback/attachments/presign',
+          {
+            method: 'POST',
+            body: JSON.stringify(request),
+          }
+        ),
+      this.config.retry
+    );
+  }
+
+  /**
+   * Confirm successful attachment upload.
+   */
+  async confirmAttachment(
+    attachmentId: string,
+    request?: AttachmentConfirmRequest
+  ): Promise<AttachmentStatusResponse> {
+    return withRetry(
+      () =>
+        this.request<AttachmentStatusResponse>(
+          `/v1/feedback/attachments/${attachmentId}/confirm`,
+          {
+            method: 'POST',
+            body: request ? JSON.stringify(request) : undefined,
+          }
+        ),
+      this.config.retry
+    );
+  }
+
+  /**
+   * Report attachment upload failure.
+   * This is a terminal state, so no retry is applied.
+   */
+  async reportAttachmentFailure(
+    attachmentId: string,
+    error?: string
+  ): Promise<AttachmentStatusResponse> {
+    return this.request<AttachmentStatusResponse>(
+      `/v1/feedback/attachments/${attachmentId}/fail`,
+      {
+        method: 'POST',
+        body: error ? JSON.stringify({ error }) : undefined,
+      }
+    );
+  }
+
+  /**
+   * Get attachment status and download URLs.
+   */
+  async getAttachmentStatus(
+    attachmentId: string
+  ): Promise<AttachmentStatusResponse> {
+    return this.request<AttachmentStatusResponse>(
+      `/v1/feedback/attachments/${attachmentId}`
+    );
+  }
+
+  /**
+   * Make an authenticated request to the API.
+   */
+  private async request<T>(
+    path: string,
+    options: RequestInit = {}
+  ): Promise<T> {
+    const url = `${this.config.baseUrl}${path}`;
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'X-Publishable-Key': this.config.publishableKey,
+      ...(options.headers as Record<string, string>),
+    };
+
+    if (this.config.userToken) {
+      headers['X-User-Token'] = this.config.userToken;
+    }
+
+    // Create abort controller for timeout
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+
+    try {
+      const response = await fetch(url, {
+        ...options,
+        headers,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const errorBody = await this.parseErrorResponse(response);
+        // Only parse Retry-After for 429 responses
+        const retryAfter = response.status === 429
+          ? this.parseRetryAfter(response)
+          : undefined;
+        throw new HarkenApiError(response.status, errorBody, { retryAfter });
+      }
+
+      return (await response.json()) as T;
+    } catch (error) {
+      clearTimeout(timeoutId);
+
+      // Re-throw HarkenApiError as-is
+      if (error instanceof HarkenApiError) {
+        throw error;
+      }
+
+      // Handle abort (timeout)
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new HarkenNetworkError('Request timed out', error);
+      }
+
+      // Handle other fetch errors (network issues)
+      if (error instanceof TypeError) {
+        throw new HarkenNetworkError('Network request failed', error);
+      }
+
+      // Unknown error
+      throw new HarkenNetworkError(
+        error instanceof Error ? error.message : 'Unknown error',
+        error instanceof Error ? error : undefined
+      );
+    }
+  }
+
+  /**
+   * Parse error response body, with fallback for non-JSON responses.
+   */
+  private async parseErrorResponse(response: Response): Promise<ErrorResponse> {
+    try {
+      return (await response.json()) as ErrorResponse;
+    } catch {
+      // Fallback for non-JSON error responses
+      return {
+        error: {
+          code: `http_${response.status}`,
+          message: response.statusText || 'Request failed',
+        },
+      };
+    }
+  }
+
+  /**
+   * Parse Retry-After header value in seconds.
+   * Supports both delta-seconds and HTTP-date formats.
+   */
+  private parseRetryAfter(response: Response): number | undefined {
+    const retryAfter = response.headers.get('Retry-After');
+    if (!retryAfter) {
+      return undefined;
+    }
+
+    // Try parsing as integer (delta-seconds)
+    const seconds = parseInt(retryAfter, 10);
+    if (!isNaN(seconds) && seconds >= 0) {
+      return seconds;
+    }
+
+    // Try parsing as HTTP-date
+    const date = Date.parse(retryAfter);
+    if (!isNaN(date)) {
+      const delayMs = date - Date.now();
+      return delayMs > 0 ? Math.ceil(delayMs / 1000) : 0;
+    }
+
+    return undefined;
+  }
+}
+
+/**
+ * Create a configured Harken client.
+ */
+export function createHarkenClient(config: HarkenClientConfig): HarkenClient {
+  return new HarkenClient(config);
+}

package/src/api/errors.ts

@@ -0,0 +1,84 @@
+import type { components } from '../types/index.js';
+
+type ErrorResponse = components['schemas']['ErrorResponse'];
+type ErrorDetail = components['schemas']['ErrorDetail'];
+
+/**
+ * Base error class for Harken API errors.
+ */
+export class HarkenError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'HarkenError';
+  }
+}
+
+/**
+ * Error thrown when the API returns an error response.
+ */
+export class HarkenApiError extends HarkenError {
+  /** HTTP status code */
+  readonly status: number;
+  /** Machine-readable error code */
+  readonly code: string;
+  /** Validation error details (if present) */
+  readonly details?: ErrorDetail[];
+  /** Retry-After value in seconds (from 429 responses) */
+  readonly retryAfter?: number;
+
+  constructor(
+    status: number,
+    response: ErrorResponse,
+    options?: { retryAfter?: number }
+  ) {
+    super(response.error.message);
+    this.name = 'HarkenApiError';
+    this.status = status;
+    this.code = response.error.code;
+    this.details = response.error.details;
+    this.retryAfter = options?.retryAfter;
+  }
+
+  /** True if this is a validation error (400) */
+  get isValidationError(): boolean {
+    return this.status === 400;
+  }
+
+  /** True if this is an auth error (401) */
+  get isUnauthorized(): boolean {
+    return this.status === 401;
+  }
+
+  /** True if this is a rate limit error (429) */
+  get isRateLimited(): boolean {
+    return this.status === 429;
+  }
+
+  /** True if this is a server error (5xx) */
+  get isServerError(): boolean {
+    return this.status >= 500;
+  }
+
+  /** True if this error is retryable */
+  get isRetryable(): boolean {
+    return this.isRateLimited || this.isServerError;
+  }
+}
+
+/**
+ * Error thrown when a network request fails.
+ */
+export class HarkenNetworkError extends HarkenError {
+  readonly cause?: Error;
+
+  constructor(message: string, cause?: Error) {
+    super(message);
+    this.name = 'HarkenNetworkError';
+    this.cause = cause;
+  }
+
+  /** Network errors are always retryable */
+  get isRetryable(): boolean {
+    return true;
+  }
+}

package/src/api/index.ts

@@ -0,0 +1,15 @@
+// Client
+export { HarkenClient, createHarkenClient } from './client';
+export type { HarkenClientConfig } from './client';
+
+// Errors
+export {
+  HarkenError,
+  HarkenApiError,
+  HarkenNetworkError,
+} from './errors';
+
+// Retry utilities
+export { withRetry, calculateRetryDelay, isRetryableError } from './retry';
+export type { RetryConfig } from './retry';
+export { DEFAULT_RETRY_CONFIG } from './retry';

package/src/api/retry.ts

@@ -0,0 +1,99 @@
+import { HarkenApiError, HarkenNetworkError } from './errors';
+
+export interface RetryConfig {
+  /** Maximum number of retry attempts (default: 3) */
+  maxRetries: number;
+  /** Base delay in ms for exponential backoff (default: 1000) */
+  baseDelay: number;
+  /** Maximum delay in ms (default: 30000) */
+  maxDelay: number;
+  /** Jitter factor 0-1 to randomize delays (default: 0.1) */
+  jitter: number;
+}
+
+export const DEFAULT_RETRY_CONFIG: RetryConfig = {
+  maxRetries: 3,
+  baseDelay: 1000,
+  maxDelay: 30000,
+  jitter: 0.1,
+};
+
+/**
+ * Calculate delay for a retry attempt with exponential backoff and jitter.
+ */
+export function calculateRetryDelay(
+  attempt: number,
+  config: RetryConfig,
+  retryAfter?: number
+): number {
+  // If server specified Retry-After, respect it
+  if (retryAfter !== undefined && retryAfter > 0) {
+    return Math.min(retryAfter * 1000, config.maxDelay);
+  }
+
+  // Exponential backoff: baseDelay * 2^attempt
+  const exponentialDelay = config.baseDelay * Math.pow(2, attempt);
+  const cappedDelay = Math.min(exponentialDelay, config.maxDelay);
+
+  // Add jitter
+  const jitterRange = cappedDelay * config.jitter;
+  const jitter = (Math.random() - 0.5) * 2 * jitterRange;
+
+  return Math.max(0, cappedDelay + jitter);
+}
+
+/**
+ * Check if an error is retryable.
+ */
+export function isRetryableError(
+  error: unknown
+): error is HarkenApiError | HarkenNetworkError {
+  if (error instanceof HarkenApiError) {
+    return error.isRetryable;
+  }
+  if (error instanceof HarkenNetworkError) {
+    return error.isRetryable;
+  }
+  return false;
+}
+
+/**
+ * Sleep for a given number of milliseconds.
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Execute a function with retry logic.
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  config: Partial<RetryConfig> = {}
+): Promise<T> {
+  const fullConfig = { ...DEFAULT_RETRY_CONFIG, ...config };
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt <= fullConfig.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      // Don't retry if this is the last attempt or error isn't retryable
+      if (attempt >= fullConfig.maxRetries || !isRetryableError(error)) {
+        throw error;
+      }
+
+      // Calculate delay, respecting Retry-After header if present
+      const retryAfter =
+        error instanceof HarkenApiError ? error.retryAfter : undefined;
+
+      const delay = calculateRetryDelay(attempt, fullConfig, retryAfter);
+      await sleep(delay);
+    }
+  }
+
+  // Should never reach here, but TypeScript needs this
+  throw lastError;
+}