@syncular/core 0.1.3 → 0.2.0

package/src/error-responses.ts

@@ -1,423 +0,0 @@
-import type {
-  ErrorResponse,
-  SyncularErrorCategory,
-  SyncularErrorRecommendedAction,
-} from './schemas/common';
-
-export const SYNCULAR_ERROR_DEFINITIONS = {
-  'sync.auth_required': {
-    category: 'auth-required',
-    retryable: true,
-    recommendedAction: 'refreshAuth',
-    message: 'Authentication is required.',
-  },
-  'sync.auth_lease_missing': {
-    category: 'auth-required',
-    retryable: true,
-    recommendedAction: 'refreshAuth',
-    message: 'The queued commit is missing required auth lease provenance.',
-  },
-  'sync.auth_lease_invalid': {
-    category: 'auth-required',
-    retryable: true,
-    recommendedAction: 'refreshAuth',
-    message: 'The queued commit auth lease provenance is invalid.',
-  },
-  'sync.auth_lease_expired': {
-    category: 'auth-required',
-    retryable: true,
-    recommendedAction: 'refreshAuth',
-    message: 'The queued commit auth lease expired before replay.',
-  },
-  'sync.auth_lease_schema_mismatch': {
-    category: 'schema-mismatch',
-    retryable: false,
-    recommendedAction: 'regenerateClient',
-    message:
-      'The queued commit auth lease was issued for an incompatible schema.',
-  },
-  'sync.auth_lease_scope_mismatch': {
-    category: 'forbidden',
-    retryable: false,
-    recommendedAction: 'checkPermissions',
-    message: 'The queued commit auth lease does not cover the pushed scopes.',
-  },
-  'sync.auth_lease_scope_revoked': {
-    category: 'scope-revoked',
-    retryable: false,
-    recommendedAction: 'checkPermissions',
-    message: 'The queued commit auth lease scope was revoked.',
-  },
-  'sync.auth_lease_business_rejected': {
-    category: 'conflict',
-    retryable: false,
-    recommendedAction: 'resolveConflict',
-    message: 'The queued commit auth lease was rejected by application policy.',
-  },
-  'sync.forbidden': {
-    category: 'forbidden',
-    retryable: false,
-    recommendedAction: 'checkPermissions',
-    message: 'The authenticated actor is not allowed to access this resource.',
-  },
-  'sync.invalid_request': {
-    category: 'invalid-request',
-    retryable: false,
-    recommendedAction: 'fixRequest',
-    message: 'The sync request is invalid.',
-  },
-  'sync.invalid_client_id': {
-    category: 'invalid-request',
-    retryable: false,
-    recommendedAction: 'resetClientId',
-    message: 'The client id cannot be used for this actor.',
-  },
-  'sync.invalid_subscription': {
-    category: 'invalid-request',
-    retryable: false,
-    recommendedAction: 'fixRequest',
-    message: 'The subscription is invalid.',
-  },
-  'sync.empty_commit': {
-    category: 'invalid-request',
-    retryable: false,
-    recommendedAction: 'fixRequest',
-    message: 'The pushed commit has no operations.',
-  },
-  'sync.unknown_table': {
-    category: 'schema-mismatch',
-    retryable: false,
-    recommendedAction: 'regenerateClient',
-    message: 'The operation targets a table unknown to this server.',
-  },
-  'sync.unsupported_operation': {
-    category: 'invalid-request',
-    retryable: false,
-    recommendedAction: 'fixRequest',
-    message: 'The operation type is not supported for this table.',
-  },
-  'sync.row_missing': {
-    category: 'not-found',
-    retryable: false,
-    recommendedAction: 'forceResync',
-    message: 'The operation base row is missing on the server.',
-  },
-  'sync.version_conflict': {
-    category: 'conflict',
-    retryable: false,
-    recommendedAction: 'resolveConflict',
-    message: 'The operation conflicts with a newer server row version.',
-  },
-  'sync.constraint_violation': {
-    category: 'invalid-request',
-    retryable: false,
-    recommendedAction: 'fixRequest',
-    message: 'The operation violates a server-side data constraint.',
-  },
-  'sync.missing_scopes': {
-    category: 'internal',
-    retryable: false,
-    recommendedAction: 'inspectServer',
-    message: 'The server handler emitted a change without scope metadata.',
-  },
-  'sync.idempotency_cache_miss': {
-    category: 'internal',
-    retryable: true,
-    recommendedAction: 'retryLater',
-    message: 'The server could not read the cached idempotent push result.',
-  },
-  'sync.too_many_operations': {
-    category: 'invalid-request',
-    retryable: false,
-    recommendedAction: 'splitBatch',
-    message: 'The push contains too many operations.',
-  },
-  'sync.not_found': {
-    category: 'not-found',
-    retryable: false,
-    recommendedAction: 'forceResync',
-    message: 'The requested sync resource was not found.',
-  },
-  'sync.rate_limited': {
-    category: 'rate-limited',
-    retryable: true,
-    recommendedAction: 'retryLater',
-    message: 'The request was rate limited.',
-  },
-  'sync.schema_mismatch': {
-    category: 'schema-mismatch',
-    retryable: false,
-    recommendedAction: 'regenerateClient',
-    message: 'The generated client schema is not compatible with this server.',
-  },
-  'sync.client_schema_unsupported': {
-    category: 'schema-mismatch',
-    retryable: false,
-    recommendedAction: 'upgradeClient',
-    message: 'The client schema version is no longer supported by this server.',
-  },
-  'sync.integrity_rejected': {
-    category: 'integrity-rejected',
-    retryable: false,
-    recommendedAction: 'forceResync',
-    message: 'Sync data failed integrity verification.',
-  },
-  'sync.scope_revoked': {
-    category: 'scope-revoked',
-    retryable: false,
-    recommendedAction: 'checkPermissions',
-    message: 'A synced subscription scope was revoked.',
-  },
-  'sync.offline': {
-    category: 'offline',
-    retryable: true,
-    recommendedAction: 'retryLater',
-    message: 'The client is offline.',
-  },
-  'sync.websocket_not_configured': {
-    category: 'server',
-    retryable: false,
-    recommendedAction: 'inspectServer',
-    message: 'The realtime websocket route is not configured.',
-  },
-  'sync.websocket_connection_limit': {
-    category: 'rate-limited',
-    retryable: true,
-    recommendedAction: 'retryLater',
-    message: 'The realtime websocket connection limit was reached.',
-  },
-  'sync.transport_failed': {
-    category: 'transport',
-    retryable: true,
-    recommendedAction: 'retryLater',
-    message: 'The sync transport failed.',
-  },
-  'runtime.busy': {
-    category: 'rate-limited',
-    retryable: true,
-    recommendedAction: 'retryLater',
-    message: 'The Syncular runtime is busy.',
-  },
-  'runtime.limit_exceeded': {
-    category: 'limit-exceeded',
-    retryable: false,
-    recommendedAction: 'reduceInput',
-    message: 'A Syncular runtime limit was exceeded.',
-  },
-  'runtime.config_invalid': {
-    category: 'invalid-request',
-    retryable: false,
-    recommendedAction: 'fixRequest',
-    message: 'The Syncular runtime configuration is invalid.',
-  },
-  'runtime.codegen_mismatch': {
-    category: 'schema-mismatch',
-    retryable: false,
-    recommendedAction: 'regenerateClient',
-    message: 'The generated client code is not compatible with the runtime.',
-  },
-  'runtime.internal': {
-    category: 'internal',
-    retryable: false,
-    recommendedAction: 'inspectServer',
-    message: 'The Syncular runtime failed internally.',
-  },
-  'storage.failed': {
-    category: 'storage',
-    retryable: false,
-    recommendedAction: 'inspectStorage',
-    message: 'The local Syncular storage operation failed.',
-  },
-  'worker.closed': {
-    category: 'invalid-request',
-    retryable: false,
-    recommendedAction: 'fixRequest',
-    message: 'The Syncular browser worker client is closed.',
-  },
-  'worker.not_open': {
-    category: 'invalid-request',
-    retryable: false,
-    recommendedAction: 'fixRequest',
-    message: 'The Syncular browser worker is not open.',
-  },
-  'worker.protocol_mismatch': {
-    category: 'schema-mismatch',
-    retryable: false,
-    recommendedAction: 'regenerateClient',
-    message: 'The Syncular browser worker protocol is incompatible.',
-  },
-  'worker.request_timeout': {
-    category: 'rate-limited',
-    retryable: true,
-    recommendedAction: 'retryLater',
-    message: 'The Syncular browser worker request timed out.',
-  },
-  'worker.failed': {
-    category: 'internal',
-    retryable: false,
-    recommendedAction: 'recreateClient',
-    message: 'The Syncular browser worker failed.',
-  },
-  'worker.message_unreadable': {
-    category: 'internal',
-    retryable: false,
-    recommendedAction: 'recreateClient',
-    message: 'The Syncular browser worker sent an unreadable message.',
-  },
-  'console.auth_required': {
-    category: 'auth-required',
-    retryable: true,
-    recommendedAction: 'refreshAuth',
-    message: 'Console authentication is required.',
-  },
-  'console.forbidden_origin': {
-    category: 'forbidden',
-    retryable: false,
-    recommendedAction: 'checkPermissions',
-    message: 'The console websocket origin is not allowed.',
-  },
-  'console.invalid_request': {
-    category: 'invalid-request',
-    retryable: false,
-    recommendedAction: 'fixRequest',
-    message: 'The console request is invalid.',
-  },
-  'console.schema_unavailable': {
-    category: 'server',
-    retryable: true,
-    recommendedAction: 'retryLater',
-    message: 'The console schema is not available.',
-  },
-  'console.not_found': {
-    category: 'not-found',
-    retryable: false,
-    recommendedAction: 'inspectServer',
-    message: 'The requested console resource was not found.',
-  },
-  'console.downstream_unavailable': {
-    category: 'server',
-    retryable: true,
-    recommendedAction: 'retryLater',
-    message: 'A console downstream instance is unavailable.',
-  },
-  'console.downstream_invalid_response': {
-    category: 'server',
-    retryable: false,
-    recommendedAction: 'inspectServer',
-    message: 'A console downstream instance returned an invalid response.',
-  },
-  'console.internal': {
-    category: 'internal',
-    retryable: false,
-    recommendedAction: 'inspectServer',
-    message: 'The console route failed internally.',
-  },
-  'proxy.auth_required': {
-    category: 'auth-required',
-    retryable: true,
-    recommendedAction: 'refreshAuth',
-    message: 'Proxy authentication is required.',
-  },
-  'proxy.forbidden_origin': {
-    category: 'forbidden',
-    retryable: false,
-    recommendedAction: 'checkPermissions',
-    message: 'The proxy websocket origin is not allowed.',
-  },
-  'proxy.connection_limit': {
-    category: 'rate-limited',
-    retryable: true,
-    recommendedAction: 'retryLater',
-    message: 'The proxy websocket connection limit was reached.',
-  },
-  'blob.invalid_request': {
-    category: 'blob',
-    retryable: false,
-    recommendedAction: 'fixRequest',
-    message: 'The blob request is invalid.',
-  },
-  'blob.storage_not_configured': {
-    category: 'blob',
-    retryable: false,
-    recommendedAction: 'inspectServer',
-    message: 'Blob storage is not configured.',
-  },
-  'blob.too_large': {
-    category: 'blob',
-    retryable: false,
-    recommendedAction: 'fixRequest',
-    message: 'The blob is too large.',
-  },
-  'blob.not_found': {
-    category: 'blob',
-    retryable: false,
-    recommendedAction: 'fixRequest',
-    message: 'The blob was not found.',
-  },
-  'blob.forbidden': {
-    category: 'forbidden',
-    retryable: false,
-    recommendedAction: 'checkPermissions',
-    message: 'The authenticated actor is not allowed to access this blob.',
-  },
-  'blob.invalid_token': {
-    category: 'auth-required',
-    retryable: true,
-    recommendedAction: 'refreshAuth',
-    message: 'The blob token is invalid or expired.',
-  },
-  'blob.upload_failed': {
-    category: 'blob',
-    retryable: true,
-    recommendedAction: 'retryLater',
-    message: 'The blob upload failed.',
-  },
-  'blob.hash_mismatch': {
-    category: 'integrity-rejected',
-    retryable: false,
-    recommendedAction: 'fixRequest',
-    message: 'The blob content hash does not match.',
-  },
-  'blob.size_mismatch': {
-    category: 'blob',
-    retryable: false,
-    recommendedAction: 'fixRequest',
-    message: 'The blob size does not match.',
-  },
-} as const satisfies Record<
-  string,
-  {
-    category: SyncularErrorCategory;
-    retryable: boolean;
-    recommendedAction: SyncularErrorRecommendedAction;
-    message: string;
-  }
->;
-
-export type SyncularErrorCode = keyof typeof SYNCULAR_ERROR_DEFINITIONS;
-
-export interface CreateSyncularErrorResponseOptions {
-  message?: string;
-  details?: Record<string, unknown>;
-}
-
-export function createSyncularErrorResponse(
-  code: SyncularErrorCode,
-  options: CreateSyncularErrorResponseOptions = {}
-): ErrorResponse & {
-  code: SyncularErrorCode;
-  category: SyncularErrorCategory;
-  retryable: boolean;
-  recommendedAction: SyncularErrorRecommendedAction;
-} {
-  const definition = SYNCULAR_ERROR_DEFINITIONS[code];
-  return {
-    error: code,
-    code,
-    message: options.message ?? definition.message,
-    category: definition.category,
-    retryable: definition.retryable,
-    recommendedAction: definition.recommendedAction,
-    ...(options.details ? { details: options.details } : {}),
-  };
-}

package/src/http/api-client.ts

@@ -1,39 +0,0 @@
-import createClient from 'openapi-fetch';
-import type { paths } from './generated/api';
-import type { ClientOptions } from './shared';
-
-export type SyncClient = ReturnType<typeof createClient<paths>>;
-
-/**
- * Create a typed API client for the full Syncular API.
- *
- * Returns an openapi-fetch client with full type safety for all endpoints.
- */
-export function createApiClient(options: ClientOptions): SyncClient {
-  const client = createClient<paths>({
-    baseUrl: options.baseUrl,
-    ...(options.fetch && { fetch: options.fetch }),
-  });
-
-  const getHeaders = options.getHeaders;
-  const transportPath = options.transportPath ?? 'direct';
-
-  client.use({
-    async onRequest({ request }) {
-      if (getHeaders) {
-        const headers = await getHeaders();
-        for (const [key, value] of Object.entries(headers)) {
-          request.headers.set(key, value);
-        }
-      }
-
-      if (!request.headers.has('x-syncular-transport-path')) {
-        request.headers.set('x-syncular-transport-path', transportPath);
-      }
-
-      return request;
-    },
-  });
-
-  return client;
-}

package/src/http/blob.ts

@@ -1,95 +0,0 @@
-import type { SyncTransport, SyncTransportBlobs } from '@syncular/core';
-import { SyncTransportError } from '@syncular/core';
-import { executeWithAuthRetry, getErrorMessage } from './shared';
-import {
-  createTransportApiClient,
-  createTransportAuthRetryResolver,
-  HTTP_TRANSPORT_SOURCE,
-  type HttpTransportSource,
-} from './transport-client';
-
-type HttpTransportWithSource = SyncTransport & {
-  [HTTP_TRANSPORT_SOURCE]?: HttpTransportSource;
-};
-
-export function createHttpTransportBlobs(
-  source: HttpTransportSource
-): SyncTransportBlobs {
-  const client = createTransportApiClient(source);
-  const resolveAuthRetry = createTransportAuthRetryResolver(source);
-
-  return {
-    async initiateUpload(args) {
-      const { data, error, response } = await executeWithAuthRetry(
-        (signal) => client.initiateUpload(args, signal),
-        undefined,
-        'blobInitiateUpload',
-        resolveAuthRetry
-      );
-
-      if (error || !data) {
-        throw new SyncTransportError(
-          `Blob upload init failed: ${getErrorMessage(error) || response.statusText}`,
-          response.status
-        );
-      }
-
-      return data;
-    },
-
-    async completeUpload(hash) {
-      const { data, error } = await executeWithAuthRetry(
-        (signal) => client.completeUpload(hash, signal),
-        undefined,
-        'blobCompleteUpload',
-        resolveAuthRetry
-      );
-
-      if (error || !data) {
-        return {
-          ok: false,
-          error: getErrorMessage(error) || 'Complete upload failed',
-        };
-      }
-
-      return data;
-    },
-
-    async getDownloadUrl(hash) {
-      const { data, error, response } = await executeWithAuthRetry(
-        (signal) => client.getDownloadUrl(hash, signal),
-        undefined,
-        'blobGetDownloadUrl',
-        resolveAuthRetry
-      );
-
-      if (error || !data) {
-        throw new SyncTransportError(
-          `Get download URL failed: ${getErrorMessage(error) || response.statusText}`,
-          response.status
-        );
-      }
-
-      return data;
-    },
-  };
-}
-
-export function ensureHttpTransportBlobs(
-  transport: SyncTransport
-): SyncTransportBlobs | null {
-  if (transport.blobs) {
-    return transport.blobs;
-  }
-
-  const source = (transport as HttpTransportWithSource)[HTTP_TRANSPORT_SOURCE];
-  if (!source) {
-    return null;
-  }
-
-  const blobs = createHttpTransportBlobs(source);
-  transport.blobs = blobs;
-  return blobs;
-}
-
-export type { SyncClient } from './api-client';