uploados 0.1.0

package/src/normalizeUploadOptions.ts

@@ -0,0 +1,132 @@
+import type {
+  CompressionOptions,
+  CompressionPreset,
+  CreateUploadOptions,
+  DirectUploadOptions,
+  ProviderUploadOptions,
+  UploadErrorPayload,
+  UploadHttpMethod,
+  UploadNetworkPolicy,
+  UploaderConfig,
+} from './Uploados.types';
+
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_METHOD: UploadHttpMethod = 'PUT';
+const DEFAULT_NETWORK_POLICY: UploadNetworkPolicy = 'wait';
+const DEFAULT_BACKGROUND = false;
+
+function throwValidationError(
+  message: string,
+  code: UploadErrorPayload['code'] = 'UNKNOWN'
+): never {
+  const error: UploadErrorPayload = {
+    code,
+    message,
+    retryable: false,
+    taskId: '',
+  };
+  throw error;
+}
+
+export function assertFutureUploadOptionsSupported(
+  compression?: CompressionOptions,
+  multipart?: boolean
+): void {
+  if (compression?.enabled === true && compression.preset) {
+    const validPresets: CompressionPreset[] = ['balanced', 'inspection', 'avatar'];
+    if (!validPresets.includes(compression.preset)) {
+      throwValidationError(
+        `Unsupported compression preset "${compression.preset}". Use balanced, inspection, or avatar.`,
+        'COMPRESSION_FAILED'
+      );
+    }
+  }
+
+  if (multipart === true) {
+    throwValidationError(
+      'Multipart uploads are not available yet. Use direct signed-URL uploads until P1-E ships.',
+      'MULTIPART_FAILED'
+    );
+  }
+}
+
+export function normalizeDirectUploadOptions(
+  config: UploaderConfig,
+  input: DirectUploadOptions
+): CreateUploadOptions {
+  assertFutureUploadOptionsSupported(input.compression, input.multipart);
+
+  const localUri = input.file.trim();
+  const uploadUrl = input.uploadUrl.trim();
+  if (!localUri) {
+    throwValidationError('Upload file URI is required.', 'FILE_NOT_FOUND');
+  }
+  if (!uploadUrl) {
+    throwValidationError('Upload URL is required.', 'PROVIDER_ERROR');
+  }
+
+  const background = input.background ?? config.background ?? DEFAULT_BACKGROUND;
+  const networkPolicy = background
+    ? 'wait'
+    : (input.networkPolicy ?? config.networkPolicy ?? DEFAULT_NETWORK_POLICY);
+  const maxAttempts = Math.max(
+    1,
+    input.retry?.maxAttempts ?? config.retry?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS
+  );
+
+  return {
+    localUri,
+    uploadUrl,
+    method: input.method ?? DEFAULT_METHOD,
+    headers: input.headers ?? {},
+    background,
+    networkPolicy,
+    retry: { maxAttempts },
+    compression: input.compression,
+  };
+}
+
+export function normalizeProviderUploadOptions(
+  config: UploaderConfig,
+  input: ProviderUploadOptions,
+  signed: {
+    uploadUrl: string;
+    method?: UploadHttpMethod;
+    headers?: Record<string, string>;
+  }
+): CreateUploadOptions {
+  assertFutureUploadOptionsSupported(input.compression, input.multipart);
+
+  const localUri = input.file.trim();
+  const uploadUrl = signed.uploadUrl.trim();
+  const key = input.key.trim();
+  if (!localUri) {
+    throwValidationError('Upload file URI is required.', 'FILE_NOT_FOUND');
+  }
+  if (!key) {
+    throwValidationError('Upload key is required.', 'PROVIDER_ERROR');
+  }
+  if (!uploadUrl) {
+    throwValidationError('Provider did not return an upload URL.', 'PROVIDER_ERROR');
+  }
+
+  const background = input.background ?? config.background ?? DEFAULT_BACKGROUND;
+  const networkPolicy = background
+    ? 'wait'
+    : (input.networkPolicy ?? config.networkPolicy ?? DEFAULT_NETWORK_POLICY);
+  const maxAttempts = Math.max(
+    1,
+    input.retry?.maxAttempts ?? config.retry?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS
+  );
+
+  return {
+    localUri,
+    uploadUrl,
+    method: signed.method ?? DEFAULT_METHOD,
+    headers: signed.headers ?? {},
+    background,
+    networkPolicy,
+    retry: { maxAttempts },
+    compression: input.compression,
+  };
+}

package/src/providers/defineUploadProvider.ts

@@ -0,0 +1,75 @@
+import type {
+  CompleteMultipartInput,
+  CompleteMultipartResult,
+  CreateMultipartInput,
+  CreateMultipartResult,
+  SignPartInput,
+  SignedPartResult,
+  UploadHttpMethod,
+  UploadProvider,
+} from '../Uploados.types';
+
+export type ProviderUploadUrlInput = {
+  key: string;
+  contentType?: string;
+  metadata?: Record<string, string>;
+};
+
+export type ProviderUploadUrlResult = {
+  url: string;
+  method?: UploadHttpMethod;
+  headers?: Record<string, string>;
+};
+
+export type UploadProviderDefinition = {
+  getUploadUrl?: (input: ProviderUploadUrlInput) => Promise<ProviderUploadUrlResult>;
+  createMultipartUpload?: (input: CreateMultipartInput) => Promise<CreateMultipartResult>;
+  signPart?: (input: SignPartInput) => Promise<SignedPartResult>;
+  completeMultipartUpload?: (input: CompleteMultipartInput) => Promise<CompleteMultipartResult>;
+  abortMultipartUpload?: (input: { key: string; uploadId: string }) => Promise<void>;
+};
+
+export function defineUploadProvider(definition: UploadProviderDefinition): UploadProvider {
+  return {
+    getUploadUrl: definition.getUploadUrl,
+    createMultipartUpload: definition.createMultipartUpload,
+    signPart: definition.signPart,
+    completeMultipartUpload: definition.completeMultipartUpload,
+    abortMultipartUpload: definition.abortMultipartUpload,
+  };
+}
+
+export function assertUploadProvider(provider: UploadProvider | undefined): UploadProvider {
+  if (!provider) {
+    throw providerError('Upload provider is required for provider-based uploads.');
+  }
+  return provider;
+}
+
+export function assertProviderMultipartSupported(provider: UploadProvider): void {
+  if (typeof provider.createMultipartUpload !== 'function') {
+    throw providerError('Provider must implement createMultipartUpload.');
+  }
+  if (typeof provider.signPart !== 'function') {
+    throw providerError('Provider must implement signPart.');
+  }
+  if (typeof provider.completeMultipartUpload !== 'function') {
+    throw providerError('Provider must implement completeMultipartUpload.');
+  }
+}
+
+export function assertProviderDirectUploadSupported(provider: UploadProvider): void {
+  if (typeof provider.getUploadUrl !== 'function') {
+    throw providerError('Provider must implement getUploadUrl for direct signed-URL uploads.');
+  }
+}
+
+function providerError(
+  message: string
+): Error & { code: string; retryable: boolean; taskId: string } {
+  return Object.assign(new Error(message), {
+    code: 'PROVIDER_ERROR',
+    retryable: false,
+    taskId: '',
+  });
+}

package/src/providers/multipartPlan.ts

@@ -0,0 +1,43 @@
+export const DEFAULT_MULTIPART_PART_SIZE = 8 * 1024 * 1024;
+export const MIN_MULTIPART_PART_SIZE = 5 * 1024 * 1024;
+
+export type MultipartUploadPlan = {
+  partSize: number;
+  partCount: number;
+  totalBytes: number;
+};
+
+export function createMultipartUploadPlan(
+  totalBytes: number,
+  partSize: number = DEFAULT_MULTIPART_PART_SIZE
+): MultipartUploadPlan {
+  if (!Number.isFinite(totalBytes) || totalBytes <= 0) {
+    throw Object.assign(new Error('File size must be greater than zero for multipart uploads.'), {
+      code: 'FILE_NOT_FOUND',
+      retryable: false,
+      taskId: '',
+    });
+  }
+
+  const normalizedPartSize = Math.max(MIN_MULTIPART_PART_SIZE, Math.floor(partSize));
+  const partCount = Math.max(1, Math.ceil(totalBytes / normalizedPartSize));
+
+  return {
+    partSize: normalizedPartSize,
+    partCount,
+    totalBytes,
+  };
+}
+
+export function validateMultipartPartNumber(partNumber: number, partCount: number): void {
+  if (!Number.isInteger(partNumber) || partNumber < 1 || partNumber > partCount) {
+    throw Object.assign(
+      new Error(`Invalid multipart part number ${partNumber}. Expected 1..${partCount}.`),
+      {
+        code: 'MULTIPART_FAILED',
+        retryable: false,
+        taskId: '',
+      }
+    );
+  }
+}

package/tsconfig.json

@@ -0,0 +1,42 @@
+{
+  "compilerOptions": {
+    "lib": [
+      "dom",
+      "DOM.Iterable",
+      "esnext"
+    ],
+    "types": [
+      "jest"
+    ],
+    "typeRoots": [
+      "./ts-declarations",
+      "./node_modules/@types"
+    ],
+    "jsx": "react-native",
+    "target": "esnext",
+    "moduleResolution": "bundler",
+    "module": "esnext",
+    "moduleDetection": "force",
+    "esModuleInterop": true,
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+    "inlineSources": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noFallthroughCasesInSwitch": true,
+    "noPropertyAccessFromIndexSignature": false,
+    "noImplicitReturns": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": false,
+    "rootDir": "./src",
+    "outDir": "./build"
+  },
+  "include": [
+    "./src"
+  ],
+  "exclude": [
+    "**/__mocks__/*",
+    "**/__tests__/*"
+  ]
+}