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

package/src/types/openapi.ts

@@ -0,0 +1,601 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+export interface paths {
+    "/v1/feedback": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Submit feedback
+         * @description Submit user feedback from a mobile app.
+         *
+         *     **Attachments:** If `attachments` are provided, they will be linked to
+         *     this feedback and their status will be updated from 'pending' to 'uploaded'.
+         *     Only attachments in 'pending' or 'uploaded' status that are not already
+         *     linked to other feedback can be used.
+         */
+        post: operations["submitFeedback"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/feedback/attachments/presign": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Create attachment upload
+         * @description Get a presigned URL for uploading an attachment.
+         *
+         *     **Upload Flow:**
+         *     1. Call this endpoint to get a presigned upload URL
+         *     2. Upload the file directly to the presigned URL (PUT request)
+         *     3. Include the `attachment_id` in your feedback submission
+         *
+         *     **Important:** The presigned URL expires in 2 hours. The attachment record
+         *     is created immediately with status 'pending'.
+         *
+         *     **Cleanup Policy:** Attachments not linked to submitted feedback are
+         *     automatically cleaned up after a server-configured period (typically
+         *     7 days). Ensure you submit the feedback with the attachments to
+         *     complete the lifecycle.
+         */
+        post: operations["createAttachmentUpload"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/feedback/attachments/{attachment_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get attachment status
+         * @description Poll for attachment upload and processing status.
+         *     Use this to check if thumbnail generation is complete.
+         */
+        get: operations["getAttachmentStatus"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/feedback/attachments/{attachment_id}/confirm": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Confirm attachment upload
+         * @description Called by SDK after successfully uploading to the presigned URL.
+         *     Triggers server-side thumbnail generation.
+         *     Poll GET /v1/feedback/attachments/{id} for processing status.
+         */
+        post: operations["confirmAttachmentUpload"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/feedback/attachments/{attachment_id}/fail": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Report attachment upload failure
+         * @description Called by SDK when upload fails after retries exhausted.
+         *     Allows backend to clean up and track failure metrics.
+         */
+        post: operations["reportAttachmentFailure"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        /**
+         * @description Category of feedback.
+         * @enum {string}
+         */
+        FeedbackCategory: "bug" | "idea" | "ux" | "other";
+        /**
+         * @description Client platform.
+         * @enum {string}
+         */
+        Platform: "ios" | "android" | "web";
+        /**
+         * @description Attachment lifecycle status:
+         *     - pending: Presign created, awaiting upload and feedback submission
+         *     - uploaded: Attachment successfully linked to submitted feedback
+         *     - failed: Upload failed (client-reported)
+         *
+         *     **Lifecycle:**
+         *     1. SDK calls presign → status becomes 'pending'
+         *     2. SDK uploads file to presigned URL
+         *     3. SDK submits feedback with attachments → status becomes 'uploaded'
+         *
+         *     **Cleanup Policy:**
+         *     Attachments that remain in 'pending' status (not linked to feedback)
+         *     are automatically deleted after a server-configured cleanup period
+         *     (typically 7 days). This handles cases where:
+         *     - User abandons the feedback form
+         *     - Network failure prevents feedback submission
+         *     - App crashes after upload but before submission
+         * @enum {string}
+         */
+        AttachmentStatus: "pending" | "uploaded" | "failed";
+        DeviceMetadata: {
+            /**
+             * @description Version of the host application.
+             * @example 1.2.3
+             */
+            app_version?: string;
+            platform?: components["schemas"]["Platform"];
+            /**
+             * @description Device model or identifier.
+             * @example iPhone 15 Pro
+             */
+            device?: string;
+            /**
+             * @description Operating system version.
+             * @example 17.2
+             */
+            os_version?: string;
+            /**
+             * @description Device locale.
+             * @example en-US
+             */
+            locale?: string;
+        } & {
+            [key: string]: unknown;
+        };
+        FeedbackSubmission: {
+            /** @description Optional short title or subject for the feedback. */
+            title?: string;
+            /** @description The feedback message content. */
+            message: string;
+            category: components["schemas"]["FeedbackCategory"];
+            /**
+             * Format: uuid
+             * @description Anonymous device identifier (UUIDv4), stable per install.
+             *     Required - requests without anon_id will be rejected with 400.
+             */
+            anon_id: string;
+            metadata?: components["schemas"]["DeviceMetadata"];
+            /** @description List of attachment IDs from presigned uploads. */
+            attachments?: string[];
+        };
+        FeedbackSubmissionResponse: {
+            /**
+             * Format: uuid
+             * @description Unique identifier for the submitted feedback.
+             */
+            id: string;
+            /**
+             * Format: date-time
+             * @description Timestamp when feedback was created.
+             */
+            created_at: string;
+        };
+        AttachmentPresignRequest: {
+            /**
+             * @description Original filename.
+             * @example screenshot.png
+             */
+            filename: string;
+            /**
+             * @description MIME type of the file.
+             * @example image/png
+             */
+            content_type: string;
+            /** @description File size in bytes (max 10MB). */
+            size: number;
+        };
+        AttachmentPresignResponse: {
+            /**
+             * Format: uuid
+             * @description Unique identifier for the attachment.
+             */
+            attachment_id: string;
+            /**
+             * Format: uri
+             * @description Presigned URL for uploading the file.
+             */
+            upload_url: string;
+            /**
+             * Format: date-time
+             * @description Expiration time of the upload URL.
+             */
+            upload_expires_at: string;
+            status: components["schemas"]["AttachmentStatus"];
+        };
+        AttachmentConfirmRequest: {
+            /** @description Actual bytes uploaded (for verification). */
+            bytes_uploaded?: number;
+        };
+        AttachmentStatusResponse: {
+            /** Format: uuid */
+            attachment_id: string;
+            status: components["schemas"]["AttachmentStatus"];
+            /** @description Original filename. Present when known. */
+            filename?: string;
+            /** @description MIME type. Present when known. */
+            content_type?: string;
+            /** @description File size in bytes. Present when known. */
+            size?: number;
+            /**
+             * @description Error message when status is failed.
+             *     May be omitted if the failure was client-side and not reported.
+             */
+            error?: string;
+            /**
+             * @description Available URLs. Presence depends on status:
+             *     - pending: not present (file may not be uploaded yet)
+             *     - uploaded: original URL available
+             *     - failed: not present
+             */
+            urls?: components["schemas"]["AttachmentUrls"];
+        };
+        /**
+         * @description URLs for accessing attachment at different sizes.
+         *     - original: Always present when urls object exists
+         *     - thumbnail: Present for image attachments when generation succeeded
+         */
+        AttachmentUrls: {
+            /**
+             * Format: uri
+             * @description URL to original uploaded file.
+             */
+            original: string;
+            /**
+             * Format: uri
+             * @description URL to thumbnail (480px wide WebP).
+             *     Only present for image attachments where thumbnail generation succeeded.
+             *     If absent for an image, client should fall back to original or show placeholder.
+             */
+            thumbnail?: string;
+        };
+        ErrorResponse: {
+            error: {
+                /**
+                 * @description Machine-readable error code.
+                 * @example validation_error
+                 */
+                code: string;
+                /**
+                 * @description Human-readable error message.
+                 * @example Invalid request body
+                 */
+                message: string;
+                /** @description Additional error details for validation errors. */
+                details?: components["schemas"]["ErrorDetail"][];
+            };
+        };
+        ErrorDetail: {
+            /**
+             * @description Field path that caused the error.
+             * @example message
+             */
+            field: string;
+            /**
+             * @description Description of the error.
+             * @example Required field is missing
+             */
+            message: string;
+            /**
+             * @description Machine-readable error code for this field.
+             * @example required
+             */
+            code?: string;
+        };
+    };
+    responses: {
+        /** @description Invalid request body or parameters. */
+        BadRequest: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                /**
+                 * @example {
+                 *       "error": {
+                 *         "code": "validation_error",
+                 *         "message": "Invalid request body",
+                 *         "details": [
+                 *           {
+                 *             "field": "message",
+                 *             "message": "Required field is missing",
+                 *             "code": "required"
+                 *           }
+                 *         ]
+                 *       }
+                 *     }
+                 */
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description Missing or invalid API key. */
+        Unauthorized: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                /**
+                 * @example {
+                 *       "error": {
+                 *         "code": "unauthorized",
+                 *         "message": "Invalid or missing X-Publishable-Key header"
+                 *       }
+                 *     }
+                 */
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description Access denied. */
+        Forbidden: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                /**
+                 * @example {
+                 *       "error": {
+                 *         "code": "forbidden",
+                 *         "message": "Access denied"
+                 *       }
+                 *     }
+                 */
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description Resource not found. */
+        NotFound: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                /**
+                 * @example {
+                 *       "error": {
+                 *         "code": "not_found",
+                 *         "message": "Resource not found"
+                 *       }
+                 *     }
+                 */
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description Rate limit exceeded. */
+        TooManyRequests: {
+            headers: {
+                /** @description Seconds to wait before retrying. */
+                "Retry-After"?: number;
+                [name: string]: unknown;
+            };
+            content: {
+                /**
+                 * @example {
+                 *       "error": {
+                 *         "code": "rate_limited",
+                 *         "message": "Too many requests. Please try again later."
+                 *       }
+                 *     }
+                 */
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description Internal server error. */
+        InternalError: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                /**
+                 * @example {
+                 *       "error": {
+                 *         "code": "internal_error",
+                 *         "message": "An unexpected error occurred"
+                 *       }
+                 *     }
+                 */
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+    };
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    submitFeedback: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["FeedbackSubmission"];
+            };
+        };
+        responses: {
+            /** @description Feedback submitted successfully. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FeedbackSubmissionResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            429: components["responses"]["TooManyRequests"];
+            500: components["responses"]["InternalError"];
+        };
+    };
+    createAttachmentUpload: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["AttachmentPresignRequest"];
+            };
+        };
+        responses: {
+            /** @description Presigned upload URL created. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AttachmentPresignResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            429: components["responses"]["TooManyRequests"];
+            500: components["responses"]["InternalError"];
+        };
+    };
+    getAttachmentStatus: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                attachment_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Attachment status. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AttachmentStatusResponse"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+            500: components["responses"]["InternalError"];
+        };
+    };
+    confirmAttachmentUpload: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                attachment_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["AttachmentConfirmRequest"];
+            };
+        };
+        responses: {
+            /** @description Upload confirmed, processing started. */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AttachmentStatusResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+            /** @description Attachment already confirmed or failed. */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            500: components["responses"]["InternalError"];
+        };
+    };
+    reportAttachmentFailure: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                attachment_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    /** @description Error message or code from the upload failure. */
+                    error?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Failure recorded. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AttachmentStatusResponse"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+            500: components["responses"]["InternalError"];
+        };
+    };
+}

package/src/utils/index.ts

@@ -0,0 +1 @@
+export { generateUUID } from './uuid';

package/src/utils/uuid.ts

@@ -0,0 +1,77 @@
+/**
+ * Crypto interface for UUID generation.
+ * Available in React Native via Hermes or JavaScriptCore.
+ */
+declare const crypto:
+  | {
+      getRandomValues<T extends ArrayBufferView>(array: T): T;
+    }
+  | undefined;
+
+/**
+ * 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
+ */
+export function generateUUID(): string {
+  // 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(): string {
+  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(): string {
+  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: Uint8Array): string {
+  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('-');
+}