@edge-base/shared 0.1.1

package/src/errors.ts

@@ -0,0 +1,228 @@
+// ─── Error Response Format ───
+
+export interface FieldError {
+  code: string;
+  message: string;
+}
+
+export interface ErrorResponse {
+  code: number;
+  message: string;
+  /** Semantic error slug for programmatic error handling (e.g. 'token-expired', 'email-already-exists'). */
+  slug?: string;
+  data?: Record<string, FieldError>;
+}
+
+// ─── Well-known Error Slugs ───
+
+/**
+ * Well-known semantic error slugs for EdgeBase core errors.
+ * SDKs can match on `slug` instead of parsing error messages.
+ *
+ * @example
+ * ```ts
+ * try { await client.auth.signIn({ email, password }); }
+ * catch (err) {
+ *   if (err.slug === 'invalid-credentials') { ... }
+ *   if (err.slug === 'account-disabled') { ... }
+ *   if (err.slug === 'token-expired') { ... }
+ * }
+ * ```
+ */
+export const ErrorSlug = {
+  // ── 400 Validation ──
+  'validation-failed': 400,
+  'invalid-input': 400,
+  'invalid-json': 400,
+  'invalid-email': 400,
+  'password-too-short': 400,
+  'password-too-long': 400,
+  'password-policy': 400,
+  'display-name-too-long': 400,
+  'invalid-locale': 400,
+  'invalid-token': 400,
+  'token-expired': 400,
+  'challenge-expired': 400,
+  'invalid-otp': 400,
+  'no-fields-to-update': 400,
+  'mfa-already-enrolled': 400,
+  'invalid-phone': 400,
+  'foreign-key-failed': 400,
+  'constraint-failed': 400,
+
+  // ── 401 Unauthorized ──
+  'unauthenticated': 401,
+  'invalid-credentials': 401,
+  'invalid-refresh-token': 401,
+  'refresh-token-expired': 401,
+  'refresh-token-reused': 401,
+  'invalid-password': 401,
+  'invalid-totp': 401,
+  'invalid-recovery-code': 401,
+
+  // ── 403 Forbidden ──
+  'forbidden': 403,
+  'access-denied': 403,
+  'account-disabled': 403,
+  'action-not-allowed': 403,
+  'hook-rejected': 403,
+  'oauth-only': 403,
+  'anonymous-not-allowed': 403,
+
+  // ── 404 Not Found ──
+  'not-found': 404,
+  'user-not-found': 404,
+  'feature-not-enabled': 404,
+
+  // ── 405 Method Not Allowed ──
+  'method-not-allowed': 405,
+
+  // ── 409 Conflict ──
+  'already-exists': 409,
+  'email-already-exists': 409,
+  'phone-already-exists': 409,
+  'record-already-exists': 409,
+
+  // ── 429 Rate Limited ──
+  'rate-limited': 429,
+
+  // ── 500 Internal ──
+  'internal-error': 500,
+} as const;
+
+export type ErrorSlugType = keyof typeof ErrorSlug;
+
+/**
+ * EdgeBase error class extending standard Error.
+ * Used by both server and SDK for consistent error handling.
+ *
+ * @example
+ * ```ts
+ * // With slug (preferred — enables programmatic error handling):
+ * throw new EdgeBaseError(400, 'Invalid email format.', undefined, 'invalid-email');
+ *
+ * // Legacy (still supported):
+ * throw new EdgeBaseError(400, 'Invalid email format.');
+ * ```
+ */
+export class EdgeBaseError extends Error {
+  public readonly code: number;
+  public readonly data?: Record<string, FieldError>;
+  /** Semantic error slug for programmatic matching. */
+  public readonly slug?: string;
+
+  constructor(code: number, message: string, data?: Record<string, FieldError>, slug?: string) {
+    super(message);
+    this.name = 'EdgeBaseError';
+    this.code = code;
+    this.data = data;
+    this.slug = slug;
+  }
+
+  /** Alias for `code` — HTTP status code of the error. */
+  get status(): number {
+    return this.code;
+  }
+
+  toJSON(): ErrorResponse {
+    const response: ErrorResponse = {
+      code: this.code,
+      message: this.message,
+    };
+    if (this.slug) {
+      response.slug = this.slug;
+    }
+    if (this.data) {
+      response.data = this.data;
+    }
+    return response;
+  }
+}
+
+/**
+ * Create a standard error response object.
+ */
+export function createErrorResponse(
+  code: number,
+  message: string,
+  data?: Record<string, FieldError>,
+  slug?: string,
+): ErrorResponse {
+  const response: ErrorResponse = { code, message };
+  if (slug) {
+    response.slug = slug;
+  }
+  if (data) {
+    response.data = data;
+  }
+  return response;
+}
+
+// ─── Function Error ───
+
+/**
+ * Well-known error codes for App Functions.
+ * Maps semantic codes to default HTTP status codes.
+ */
+export const FunctionErrorCode = {
+  'not-found': 404,
+  'permission-denied': 403,
+  'unauthenticated': 401,
+  'invalid-argument': 400,
+  'already-exists': 409,
+  'resource-exhausted': 429,
+  'failed-precondition': 412,
+  'internal': 500,
+  'unavailable': 503,
+} as const;
+
+export type FunctionErrorCodeType = keyof typeof FunctionErrorCode;
+
+/**
+ * Structured error thrown from App Functions.
+ * Caught by the functions route handler and returned as a JSON response
+ * with the appropriate HTTP status code.
+ *
+ * @example
+ * throw new FunctionError('not-found', 'User not found');
+ * throw new FunctionError('permission-denied', 'Admin only');
+ * throw new FunctionError('invalid-argument', 'Email is required', { field: 'email' });
+ */
+export class FunctionError extends Error {
+  public readonly code: FunctionErrorCodeType | string;
+  public readonly httpStatus: number;
+  public readonly details?: Record<string, unknown>;
+
+  constructor(
+    code: FunctionErrorCodeType | string,
+    message: string,
+    details?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = 'FunctionError';
+    this.code = code;
+    this.httpStatus =
+      (FunctionErrorCode as Record<string, number>)[code] ?? 400;
+    this.details = details;
+  }
+
+  toJSON(): {
+    code: string;
+    message: string;
+    status: number;
+    details?: Record<string, unknown>;
+  } {
+    const result: {
+      code: string;
+      message: string;
+      status: number;
+      details?: Record<string, unknown>;
+    } = {
+      code: this.code,
+      message: this.message,
+      status: this.httpStatus,
+    };
+    if (this.details) result.details = this.details;
+    return result;
+  }
+}

package/src/index.ts

@@ -0,0 +1,164 @@
+export {
+  CURRENT_PLUGIN_API_VERSION,
+  defineConfig,
+  defineFunction,
+  getDbAccess,
+  getTableAccess,
+  getTableHooks,
+  getStorageBucketAccess,
+  getStorageHooks,
+  getPushAccess,
+  getPushHandlers,
+  getAuthAccess,
+  getAuthHandlers,
+  getAuthEnrichHandler,
+  getMailHooks,
+  getRoomAccess,
+  getRoomStateConfig,
+  getRoomHooks,
+  getRoomHandlers,
+  getRoomLifecycleHandlers,
+  getRoomActionHandlers,
+  getRoomTimerHandlers,
+  materializeConfig,
+} from './config.js';
+export type {
+  // ─── Core Config ───
+  EdgeBaseConfig,
+  // ─── Database-first (§1,) ───
+  DbBlock,
+  DbAdminConfig,
+  DbProvider,
+  DbAccess,
+  DbLevelRules,
+  DbRuleCtx,
+  AdminInstanceDiscovery,
+  AdminInstanceDiscoveryContext,
+  AdminInstanceDiscoveryOption,
+  ManualAdminInstanceDiscovery,
+  TableAdminInstanceDiscovery,
+  FunctionAdminInstanceDiscovery,
+  TableConfig,
+  TableAccess,
+  TableRules,
+  TableHandlers,
+  TableHooks,
+  // ─── Auth Context ───
+  AuthContext,
+  // ─── Hook Context ───
+  HookCtx,
+  // ─── Schema ───
+  FieldType,
+  SchemaField,
+  FkReference,
+  IndexConfig,
+  MigrationConfig,
+  // ─── Auth Config ───
+  AuthConfig,
+  AuthAccess,
+  AuthAccessCtx,
+  AuthAccessRule,
+  AuthHandlers,
+  AuthHandlerHooks,
+  EmailOtpConfig,
+  MagicLinkConfig,
+  MfaConfig,
+  OAuthProviderCredentialsConfig,
+  OidcProviderCredentialsConfig,
+  OAuthProvidersConfig,
+  PasskeysConfig,
+  PasswordPolicyConfig,
+  SmsConfig,
+  // ─── Email Config ───
+  EmailConfig,
+  EmailTemplateOverrides,
+  EmailSubjectOverrides,
+  MailHooks,
+  MailHookCtx,
+  MailType,
+  SmsHooks,
+  SmsHookCtx,
+  SmsType,
+  // ─── Storage (§5) ───
+  StorageConfig,
+  StorageBucketConfig,
+  StorageBucketAccess,
+  StorageBucketRules,
+  StorageHandlers,
+  StorageHooks,
+  StorageHookCtx,
+  WriteFileMeta,
+  R2FileMeta,
+  // ─── CORS / Rate Limiting ───
+  CorsConfig,
+  RateLimitingConfig,
+  // ─── Functions ───
+  FunctionsConfig,
+  CloudflareConfig,
+  FunctionDefinition,
+  FunctionTrigger,
+  FunctionTriggerType,
+  DbTrigger,
+  AuthTrigger,
+  StorageTrigger,
+  ScheduleTrigger,
+  HttpTrigger,
+  // ─── Plugin ───
+  PluginManifest,
+  PluginInstance,
+  // ─── Service Key ───
+  ServiceKeyEntry,
+  ServiceKeysConfig,
+  ServiceKeyConstraints,
+  ScopeString,
+  // ─── Captcha ───
+  CaptchaConfig,
+  // ─── Push ───
+  PushConfig,
+  PushAccess,
+  PushFcmConfig,
+  PushHandlers,
+  PushHookCtx,
+  PushRules,
+  PushSendInput,
+  PushSendOutput,
+  // ─── Database Live ───
+  DatabaseLiveConfig,
+  // ─── KV / D1 / Vectorize ───
+  KvNamespaceConfig,
+  KvNamespaceRules,
+  D1DatabaseConfig,
+  VectorizeConfig,
+  // ─── Room v2 ───
+  RoomNamespaceConfig,
+  RoomAccess,
+  RoomMediaAccess,
+  RoomRuntimeConfig,
+  RoomRuntimeTarget,
+  RoomStateConfig,
+  RoomHooks,
+  RoomMemberHooks,
+  RoomStateHooks,
+  RoomSignalHooks,
+  RoomMediaHooks,
+  RoomSessionHooks,
+  RoomHandlers,
+  RoomLifecycleHandlers,
+  RoomCreateHandler,
+  RoomJoinHandler,
+  RoomLeaveHandler,
+  RoomDestroyHandler,
+  RoomActionHandlers,
+  RoomTimerHandlers,
+  RoomSender,
+  RoomMemberInfo,
+  RoomServerAPI,
+  RoomHandlerContext,
+  RoomTableProxy,
+  RoomDbProxy,
+} from './config.js';
+
+export { EdgeBaseError, createErrorResponse, FunctionError, FunctionErrorCode } from './errors.js';
+export type { ErrorResponse, FieldError, FunctionErrorCodeType } from './errors.js';
+
+export type { FilterOperator, SortDirection } from './types.js';

package/src/types.ts

@@ -0,0 +1,16 @@
+// ─── Common Utility Types ───
+
+export type FilterOperator =
+  | '=='
+  | '!='
+  | '>'
+  | '<'
+  | '>='
+  | '<='
+  | 'contains'
+  | 'contains-any'
+  | 'in'
+  | 'not in'
+  | 'not-in';
+
+export type SortDirection = 'asc' | 'desc';