uploados 0.1.0

package/readme.md

@@ -0,0 +1,169 @@
+# uploados
+
+Native signed-URL uploads for Expo and React Native apps.
+
+uploados is an Expo native module that runs direct `PUT`/`POST` uploads from iOS and Android native code. The current release focuses on direct signed-URL uploads, provider-based presign, file staging, native JPEG compression presets, retry, progress events, and a persistent upload queue.
+
+Native multipart uploads are not wired yet. Passing `multipart: true` currently throws a typed `MULTIPART_FAILED` error.
+
+## Current status
+
+| Capability | Status |
+|------------|--------|
+| Direct signed-URL uploads | Shipped on iOS and Android |
+| Provider-based direct presign (`getUploadUrl`) | Shipped |
+| File staging for picker and content URIs | Shipped |
+| Persistent queue and restore | Shipped |
+| Native JPEG compression presets | Shipped |
+| Android foreground upload notification | Shipped for background WorkManager uploads; customization is not exposed yet |
+| iOS Live Activity / Dynamic Island | Not implemented; build app-owned progress UI from upload events |
+| Native multipart engine | Deferred; use direct uploads for now |
+| Web | Throws `UNSUPPORTED_PLATFORM` by design |
+
+## Installation
+
+Use Expo to install the package so peer versions stay aligned with your SDK:
+
+```bash
+npx expo install uploados
+npx expo doctor
+```
+
+Then rebuild native projects:
+
+```bash
+npx expo prebuild
+npx pod-install
+npx expo run:ios
+npx expo run:android
+```
+
+Expo Go does not load custom native modules, so use a development build.
+
+Current peer metadata targets Expo SDK 52 through 56:
+
+- `expo >=52.0.0 <57.0.0`
+- `react-native >=0.76.0 <0.86.0`
+- `react >=18.3.1 <20.0.0`
+
+## Direct signed-URL upload
+
+```ts
+import { createUploader } from 'uploados';
+
+const uploader = createUploader({
+  background: true,
+  retry: { maxAttempts: 5 },
+});
+
+const task = await uploader.upload({
+  file: imageUri,
+  uploadUrl: signedPutUrl,
+  headers: { 'Content-Type': 'image/jpeg' },
+  compression: { enabled: true, preset: 'balanced' },
+});
+
+task.onProgress((progress) => {
+  console.log(progress.percentage);
+});
+
+task.onComplete((snapshot) => {
+  console.log(snapshot.id, snapshot.state);
+});
+
+task.onFailed((error) => {
+  console.log(error.code, error.message);
+});
+```
+
+## Provider-based direct upload
+
+Use `defineUploadProvider` when your backend accepts an object key and returns a presigned URL. Multipart callbacks are optional and unused until the native multipart path ships.
+
+```ts
+import { createUploader, defineUploadProvider } from 'uploados';
+
+const uploader = createUploader({
+  provider: defineUploadProvider({
+    getUploadUrl: async ({ key, contentType }) => {
+      const res = await fetch('https://your-api/presign', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ key, contentType }),
+      });
+      return res.json();
+    },
+  }),
+});
+
+await uploader.upload({
+  file: imageUri,
+  key: 'uploads/photo.jpg',
+  contentType: 'image/jpeg',
+  compression: { enabled: true, preset: 'inspection' },
+});
+```
+
+## Compression
+
+Compression runs natively before upload and leaves the original file unchanged. Output is JPEG, and `compressed` events include `CompressionStats` with `originalSize`, `optimizedSize`, `preset`, and `format: 'jpeg'`.
+
+```ts
+compression: {
+  enabled: true,
+  preset: 'balanced',
+}
+```
+
+Presets:
+
+- `balanced`: default size and quality tradeoff
+- `inspection`: keeps more detail for inspection photos
+- `avatar`: smaller profile image and thumbnail output
+
+## Queue and lifecycle
+
+Each upload is stored in a native task queue. States use the exported `UploadState` union:
+
+```txt
+created -> validating -> compressing -> queued -> connecting -> uploading
+  -> verifying -> completed
+```
+
+Failures may enter `retrying` before `failed`. Cancelled tasks enter `cancelled`.
+
+Native retries reuse the same `uploadUrl` and headers. For background uploads, issue presigned URLs with enough TTL for the retry window, or create a fresh upload after an `AUTH_ERROR` / `PROVIDER_ERROR`.
+
+Use queue APIs to inspect or resume work:
+
+```ts
+const snapshots = await uploader.restoreQueue();
+const all = await uploader.getAllTasks();
+const one = await uploader.getTask(taskId);
+await uploader.cancel(taskId);
+await uploader.retry(taskId);
+```
+
+## Platform notes
+
+- iOS uses `URLSession`, including background sessions when `background: true`.
+- Android uses WorkManager and OkHttp for deferred upload work.
+- Android background uploads run as foreground WorkManager work with an ongoing upload notification. Apps targeting Android 13+ must request notification permission for the notification to be visible.
+- Android notification customization is not exposed in the JS API yet.
+- iOS Live Activity and Dynamic Island surfaces are app-owned. Subscribe to upload events and render your own progress UI if you need them.
+- Web upload APIs intentionally throw `UNSUPPORTED_PLATFORM`.
+
+## Repository development
+
+This repository uses Bun.
+
+```bash
+bun install
+EXPO_NONINTERACTIVE=1 bun run build
+bun run lint
+EXPO_NONINTERACTIVE=1 bun run test
+```
+
+## License
+
+MIT

package/src/Uploados.types.ts

@@ -0,0 +1,260 @@
+export type UploadState =
+  | 'created'
+  | 'validating'
+  | 'compressing'
+  | 'queued'
+  | 'connecting'
+  | 'uploading'
+  | 'verifying'
+  | 'retrying'
+  | 'completed'
+  | 'paused'
+  | 'failed'
+  | 'cancelled';
+
+export type UploadHttpMethod = 'PUT' | 'POST';
+
+export type UploadNetworkPolicy = 'wait' | 'failFast';
+
+export type UploadErrorPhase =
+  | 'validating'
+  | 'compressing'
+  | 'connecting'
+  | 'uploading'
+  | 'verifying'
+  | 'retrying';
+
+export type UploadProgress = {
+  bytesUploaded: number;
+  totalBytes: number;
+  percentage: number;
+};
+
+export type UploadErrorCode =
+  | 'FILE_NOT_FOUND'
+  | 'FILE_TOO_LARGE'
+  | 'NETWORK_ERROR'
+  | 'AUTH_ERROR'
+  | 'PROVIDER_ERROR'
+  | 'MULTIPART_FAILED'
+  | 'COMPRESSION_FAILED'
+  | 'BACKGROUND_RESTRICTED'
+  | 'CANCELLED'
+  | 'UNSUPPORTED_PLATFORM'
+  | 'UNKNOWN';
+
+export type UploadErrorPayload = {
+  code: UploadErrorCode;
+  message: string;
+  retryable: boolean;
+  taskId: string;
+  phase?: UploadErrorPhase;
+  httpStatus?: number;
+  providerCode?: string;
+  providerMessage?: string;
+  nativeCause?: string;
+};
+
+export type UploadFileMetadata = {
+  originalUri: string;
+  uploadUri: string;
+  isStaged: boolean;
+  sizeBytes?: number;
+};
+
+export type CompressionStats = {
+  preset: CompressionPreset;
+  originalSize: number;
+  optimizedSize: number;
+  format: 'jpeg';
+};
+
+export type UploadTaskSnapshot = {
+  id: string;
+  localUri: string;
+  file?: UploadFileMetadata;
+  uploadUrl: string;
+  method: UploadHttpMethod;
+  state: UploadState;
+  progress: UploadProgress;
+  background: boolean;
+  networkPolicy: UploadNetworkPolicy;
+  attempt: number;
+  maxAttempts: number;
+  nextRetryAt?: number;
+  createdAt: number;
+  updatedAt: number;
+  originalSize?: number;
+  optimizedSize?: number;
+  compression?: CompressionStats;
+  error?: UploadErrorPayload;
+};
+
+export type UploadRetryOptions = {
+  maxAttempts?: number;
+};
+
+export type CompressionPreset = 'balanced' | 'inspection' | 'avatar';
+
+export type CompressionOptions = {
+  enabled?: boolean;
+  preset?: CompressionPreset;
+};
+
+export type UploaderConfig = {
+  background?: boolean;
+  networkPolicy?: UploadNetworkPolicy;
+  retry?: UploadRetryOptions;
+  provider?: UploadProvider;
+};
+
+export type CreateMultipartInput = {
+  key: string;
+  contentType?: string;
+  metadata?: Record<string, string>;
+};
+
+export type CreateMultipartResult = {
+  uploadId: string;
+  key: string;
+};
+
+export type SignPartInput = {
+  key: string;
+  uploadId: string;
+  partNumber: number;
+};
+
+export type SignedPartResult = {
+  url: string;
+  method: UploadHttpMethod;
+  headers?: Record<string, string>;
+  partNumber: number;
+};
+
+export type CompletedPart = {
+  partNumber: number;
+  etag: string;
+};
+
+export type CompleteMultipartInput = {
+  key: string;
+  uploadId: string;
+  parts: CompletedPart[];
+};
+
+export type CompleteMultipartResult = {
+  key: string;
+  location?: string;
+  etag?: string;
+};
+
+export type AbortMultipartInput = {
+  key: string;
+  uploadId: string;
+};
+
+export type ProviderUploadUrlInput = {
+  key: string;
+  contentType?: string;
+  metadata?: Record<string, string>;
+};
+
+export type ProviderUploadUrlResult = {
+  url: string;
+  method?: UploadHttpMethod;
+  headers?: Record<string, string>;
+};
+
+export type UploadProvider = {
+  getUploadUrl?: (input: ProviderUploadUrlInput) => Promise<ProviderUploadUrlResult>;
+  createMultipartUpload?: (input: CreateMultipartInput) => Promise<CreateMultipartResult>;
+  signPart?: (input: SignPartInput) => Promise<SignedPartResult>;
+  completeMultipartUpload?: (input: CompleteMultipartInput) => Promise<CompleteMultipartResult>;
+  abortMultipartUpload?: (input: AbortMultipartInput) => Promise<void>;
+};
+
+/** Direct signed-URL upload supported by the current native baseline. */
+export type DirectUploadOptions = {
+  file: string;
+  uploadUrl: string;
+  method?: UploadHttpMethod;
+  headers?: Record<string, string>;
+  background?: boolean;
+  networkPolicy?: UploadNetworkPolicy;
+  retry?: UploadRetryOptions;
+  /** Reserved for P1-C. Rejected when enabled until native compression ships. */
+  compression?: CompressionOptions;
+  /** Reserved for P1-E. Rejected when true until multipart ships. */
+  multipart?: boolean;
+};
+
+/** Provider-key upload reserved for the P1-D provider contract. */
+export type ProviderUploadOptions = {
+  file: string;
+  key: string;
+  contentType?: string;
+  background?: boolean;
+  networkPolicy?: UploadNetworkPolicy;
+  retry?: UploadRetryOptions;
+  compression?: CompressionOptions;
+  multipart?: boolean;
+};
+
+export type UploadOptions = DirectUploadOptions | ProviderUploadOptions;
+
+export type UploadTaskHandle = {
+  readonly id: string;
+  readonly snapshot: UploadTaskSnapshot;
+  cancel(): Promise<UploadTaskSnapshot>;
+  retry(): Promise<UploadTaskSnapshot>;
+  getSnapshot(): Promise<UploadTaskSnapshot | null>;
+  onProgress(listener: (progress: UploadProgress) => void): () => void;
+  onComplete(listener: (task: UploadTaskSnapshot) => void): () => void;
+  onFailed(listener: (error: UploadErrorPayload) => void): () => void;
+  onCancelled(listener: () => void): () => void;
+};
+
+export type Uploader = {
+  upload(options: UploadOptions): Promise<UploadTaskHandle>;
+  cancel(taskId: string): Promise<UploadTaskSnapshot>;
+  retry(taskId: string): Promise<UploadTaskSnapshot>;
+  getTask(taskId: string): Promise<UploadTaskSnapshot | null>;
+  getAllTasks(): Promise<UploadTaskSnapshot[]>;
+  restoreQueue(): Promise<UploadTaskSnapshot[]>;
+  subscribe(listener: (event: UploadEvent) => void): () => void;
+};
+
+export type CreateUploadOptions = {
+  localUri: string;
+  uploadUrl: string;
+  method?: UploadHttpMethod;
+  headers?: Record<string, string>;
+  background?: boolean;
+  networkPolicy?: UploadNetworkPolicy;
+  retry?: UploadRetryOptions;
+  compression?: CompressionOptions;
+};
+
+export type UploadEvent =
+  | { type: 'created'; task: UploadTaskSnapshot }
+  | { type: 'compressing'; taskId: string; task: UploadTaskSnapshot }
+  | { type: 'compressed'; taskId: string; task: UploadTaskSnapshot; stats: CompressionStats }
+  | { type: 'queued'; taskId: string }
+  | { type: 'connecting'; taskId: string; task: UploadTaskSnapshot }
+  | { type: 'progress'; taskId: string; progress: UploadProgress }
+  | { type: 'verifying'; taskId: string }
+  | {
+      type: 'retrying';
+      taskId: string;
+      attempt: number;
+      delayMs: number;
+      error: UploadErrorPayload;
+    }
+  | { type: 'completed'; taskId: string; task: UploadTaskSnapshot }
+  | { type: 'failed'; taskId: string; error: UploadErrorPayload }
+  | { type: 'cancelled'; taskId: string };
+
+export type UploadosModuleEvents = {
+  onUploadEvent: (event: UploadEvent) => void;
+};

package/src/UploadosModule.ts

@@ -0,0 +1,18 @@
+import { NativeModule, requireNativeModule } from 'expo';
+
+import type {
+  CreateUploadOptions,
+  UploadosModuleEvents,
+  UploadTaskSnapshot,
+} from './Uploados.types';
+
+declare class UploadosModule extends NativeModule<UploadosModuleEvents> {
+  createUploadAsync(options: CreateUploadOptions): Promise<UploadTaskSnapshot>;
+  cancelUploadAsync(taskId: string): Promise<UploadTaskSnapshot>;
+  retryUploadAsync(taskId: string): Promise<UploadTaskSnapshot>;
+  getTaskAsync(taskId: string): Promise<UploadTaskSnapshot | null>;
+  getAllTasksAsync(): Promise<UploadTaskSnapshot[]>;
+  restoreQueueAsync(): Promise<UploadTaskSnapshot[]>;
+}
+
+export default requireNativeModule<UploadosModule>('Uploados');

package/src/UploadosModule.web.ts

@@ -0,0 +1,49 @@
+import { NativeModule, registerWebModule } from 'expo';
+
+import type {
+  CreateUploadOptions,
+  UploadErrorPayload,
+  UploadosModuleEvents,
+  UploadTaskSnapshot,
+} from './Uploados.types';
+
+function unsupported(): never {
+  const error: UploadErrorPayload = {
+    code: 'UNSUPPORTED_PLATFORM',
+    message: 'Uploados native uploads are not available on web.',
+    retryable: false,
+    taskId: '',
+  };
+  throw error;
+}
+
+class Uploados extends NativeModule<UploadosModuleEvents> {
+  async createUploadAsync(_options: CreateUploadOptions): Promise<UploadTaskSnapshot> {
+    unsupported();
+  }
+
+  async cancelUploadAsync(_taskId: string): Promise<UploadTaskSnapshot> {
+    unsupported();
+  }
+
+  async retryUploadAsync(_taskId: string): Promise<UploadTaskSnapshot> {
+    unsupported();
+  }
+
+  async getTaskAsync(_taskId: string): Promise<UploadTaskSnapshot | null> {
+    unsupported();
+  }
+
+  async getAllTasksAsync(): Promise<UploadTaskSnapshot[]> {
+    unsupported();
+  }
+
+  async restoreQueueAsync(): Promise<UploadTaskSnapshot[]> {
+    unsupported();
+  }
+}
+
+type RegisterWebModuleCompat = (moduleImplementation: typeof Uploados) => Uploados;
+
+// SDK 52 types only the one-argument form; newer SDKs support it at runtime.
+export default (registerWebModule as unknown as RegisterWebModuleCompat)(Uploados);

package/src/createUploader.ts

@@ -0,0 +1,146 @@
+import type {
+  DirectUploadOptions,
+  ProviderUploadOptions,
+  UploadErrorPayload,
+  UploadEvent,
+  UploadOptions,
+  UploadTaskHandle,
+  UploadTaskSnapshot,
+  Uploader,
+  UploaderConfig,
+} from './Uploados.types';
+import UploadosModule from './UploadosModule';
+import {
+  normalizeDirectUploadOptions,
+  normalizeProviderUploadOptions,
+} from './normalizeUploadOptions';
+import {
+  assertProviderDirectUploadSupported,
+  assertUploadProvider,
+} from './providers/defineUploadProvider';
+
+function throwMultipartNotReady(): never {
+  const error: UploadErrorPayload = {
+    code: 'MULTIPART_FAILED',
+    message:
+      'Multipart provider uploads require the P1-E native multipart engine. Use direct signed-URL uploads for now.',
+    retryable: false,
+    taskId: '',
+  };
+  throw error;
+}
+
+function isDirectUploadOptions(options: UploadOptions): options is DirectUploadOptions {
+  return 'uploadUrl' in options;
+}
+
+function isProviderUploadOptions(options: UploadOptions): options is ProviderUploadOptions {
+  return 'key' in options;
+}
+
+function getEventTaskId(event: UploadEvent): string | undefined {
+  if (event.type === 'created') {
+    return event.task.id;
+  }
+  return event.taskId;
+}
+
+function createTaskHandle(
+  snapshot: UploadTaskSnapshot,
+  subscribe: Uploader['subscribe'],
+  module: typeof UploadosModule
+): UploadTaskHandle {
+  const taskId = snapshot.id;
+
+  const onTaskEvent = <T extends UploadEvent['type']>(
+    type: T,
+    listener: (event: Extract<UploadEvent, { type: T }>) => void
+  ): (() => void) =>
+    subscribe((event) => {
+      if (getEventTaskId(event) === taskId && event.type === type) {
+        listener(event as Extract<UploadEvent, { type: T }>);
+      }
+    });
+
+  return {
+    id: taskId,
+    snapshot,
+    cancel: () => module.cancelUploadAsync(taskId),
+    retry: () => module.retryUploadAsync(taskId),
+    getSnapshot: () => module.getTaskAsync(taskId),
+    onProgress: (listener) => onTaskEvent('progress', (event) => listener(event.progress)),
+    onComplete: (listener) => onTaskEvent('completed', (event) => listener(event.task)),
+    onFailed: (listener) => onTaskEvent('failed', (event) => listener(event.error)),
+    onCancelled: (listener) => onTaskEvent('cancelled', () => listener()),
+  };
+}
+
+export function createUploader(config: UploaderConfig = {}): Uploader {
+  const listeners = new Set<(event: UploadEvent) => void>();
+  let moduleSubscription: { remove: () => void } | null = null;
+  const provider = config.provider;
+
+  const ensureModuleSubscription = () => {
+    if (moduleSubscription) {
+      return;
+    }
+    moduleSubscription = UploadosModule.addListener('onUploadEvent', (event: UploadEvent) => {
+      listeners.forEach((listener) => {
+        listener(event);
+      });
+    });
+  };
+
+  const subscribe = (listener: (event: UploadEvent) => void): (() => void) => {
+    ensureModuleSubscription();
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+      if (listeners.size === 0 && moduleSubscription) {
+        moduleSubscription.remove();
+        moduleSubscription = null;
+      }
+    };
+  };
+
+  return {
+    async upload(options: UploadOptions): Promise<UploadTaskHandle> {
+      if (isProviderUploadOptions(options)) {
+        const resolvedProvider = assertUploadProvider(provider);
+        if (options.multipart === true) {
+          throwMultipartNotReady();
+        }
+        assertProviderDirectUploadSupported(resolvedProvider);
+        const signed = await resolvedProvider.getUploadUrl!({
+          key: options.key.trim(),
+          contentType: options.contentType,
+        });
+        const normalized = normalizeProviderUploadOptions(config, options, {
+          uploadUrl: signed.url,
+          method: signed.method,
+          headers: signed.headers,
+        });
+        const snapshot = await UploadosModule.createUploadAsync(normalized);
+        return createTaskHandle(snapshot, subscribe, UploadosModule);
+      }
+
+      if (!isDirectUploadOptions(options)) {
+        throw Object.assign(new Error('Invalid upload options.'), {
+          code: 'UNKNOWN',
+          retryable: false,
+          taskId: '',
+        });
+      }
+
+      const normalized = normalizeDirectUploadOptions(config, options);
+      const snapshot = await UploadosModule.createUploadAsync(normalized);
+      return createTaskHandle(snapshot, subscribe, UploadosModule);
+    },
+    cancel: (taskId) => UploadosModule.cancelUploadAsync(taskId),
+    retry: (taskId) => UploadosModule.retryUploadAsync(taskId),
+    getTask: (taskId) => UploadosModule.getTaskAsync(taskId),
+    getAllTasks: () => UploadosModule.getAllTasksAsync(),
+    restoreQueue: () => UploadosModule.restoreQueueAsync(),
+    subscribe,
+  };
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { createUploader } from './createUploader';
+export { defineUploadProvider } from './providers/defineUploadProvider';
+export { createMultipartUploadPlan, DEFAULT_MULTIPART_PART_SIZE } from './providers/multipartPlan';
+export * from './Uploados.types';