Shared Package

@activation-sys/shared — Types, Zod schemas, constants, and error classes used across all apps.

Installation

Already included in the monorepo workspace.

import { createUserSchema, AppError, SIM_LIMITS } from '@activation-sys/shared';

Exports

// TypeScript types
export * from './types/index';

// Zod validation schemas
export * from './schemas/index';

// Constants
export * from './constants/index';

// Error classes
export { AppError, AuthError, ValidationError, NotFoundError, ActivationError, PaymentError, OperatorError, toApiResponse };

Types

All types are string unions (not TypeScript enums):

type UserRole = 'end_user' | 'b2b_admin' | 'activation_officer' | 'super_admin' | 'support' | 'admin';
type ManageableArea = 'activation-records' | 'packages' | 'officer' | 'support' | 'b2b';
type ActivationStatus = 'pending' | 'in_progress' | 'activated' | 'failed' | 'cancelled';
type OperatorSlug = 'stc' | 'mobily' | 'zain';
type IdentityType = 'citizen' | 'resident' | 'visitor';
type PaymentMethod = 'mada' | 'stc_pay' | 'apple_pay' | 'google_pay' | 'visa' | 'mastercard' | 'stripe';
type SupportedCurrency = 'USD' | 'SAR' | 'AED' | 'EUR' | 'GBP' | 'EGP';

Zod Schemas

All schemas use Zod v4 and can be used for both validation and type inference:

import { createUserSchema, activationSchema, paymentIntentSchema } from '@activation-sys/shared';

// Validate request body
const result = createUserSchema.safeParse(body);
if (!result.success) { /* handle validation error */ }
// result.data is typed as CreateUser

Available schemas: createUserSchema, updateUserSchema, operatorSchema, createOperatorSchema, packageSchema, createPackageSchema, packageFilterSchema, activationSchema, iccidValidationSchema, activationResponseSchema, paymentSchema, paymentIntentSchema, paymentStatusSchema, paymentMethodSchema, ticketSchema, createTicketSchema, createAdminUserSchema, updateAdminUserSchema.

Store schemas (from schemas/store.ts): supportedCurrencySchema, moneySchema, storeProductSchema, adminStoreProductSchema, storeDestinationSchema, storeDataAllowanceSchema, storeValiditySchema, storeProductListResponseSchema, storeDestinationsResponseSchema, storeProductListQuerySchema, storeDestinationsQuerySchema, createStoreOrderRequestSchema, storeOrderResponseSchema, storeOrderViewSchema, adminStoreOrderViewSchema, storeOrderListQuerySchema, adminStoreOrderListQuerySchema, storeOrderListResponseSchema, adminStoreOrderListResponseSchema, adminStoreProductListQuerySchema, adminStoreProductListResponseSchema, updateStoreProductSchema, updateStoreProviderSchema, esimIssuanceStateSchema, providerCatalogItemSchema, storeProviderHealthSnapshotSchema, fxRateEntrySchema, fxRatesResponseSchema, storeProviderSchema, storeProvidersResponseSchema, deviceCompatibilityEntrySchema, deviceCompatibilityResponseSchema.

Constants

SIM_LIMITS       // { citizen: 10, resident: 2, visitor: 1 }
QUEUE_NAMES      // { activation: 'activation', payment: 'payment', notification: 'notification', store: 'store-fulfillment' }
RETRY_CONFIG     // Per-queue retry configuration
ERROR_CODES      // All error code constants
STORE_SUPPORTED_CURRENCIES // ['USD', 'SAR', 'AED', 'EUR', 'GBP', 'EGP']
BASE_CURRENCY    // 'USD'
ESIM_ISSUANCE_STATES       // ['pending', 'in_flight', 'issued', 'pending_verification', 'reconciliation_required', 'failed']
ESIM_PROVIDER_ERROR_CODES  // ['OUT_OF_STOCK', 'TRANSIENT_UNAVAILABLE', 'TERMINAL_FAILURE', 'AMBIGUOUS_RESULT']
ICCID_LENGTH     // 19
DEVICE_COMPATIBILITY       // Versioned list of eSIM-capable phone models
DEVICE_COMPATIBILITY_VERSION // Current version string of the device list
resolveDeviceCompatibility // Canonical resolver: exact beats prefix, unknown never blocks

Error Classes

All errors extend AppError with bilingual messages:

import { ValidationError, NotFoundError } from '@activation-sys/shared';

throw new ValidationError('Validation failed', 'فشل التحقق', 'VALIDATION_ERROR', fieldErrors);
throw new NotFoundError('User not found', 'المستخدم غير موجود');

// Convert to API response (respects Accept-Language header)
toApiResponse(error, 'ar'); // Returns Arabic message
toApiResponse(error, 'en'); // Returns English message

Class	Status	Use Case
AppError	Custom	Base error class
AuthError	401/403	Authentication/authorization failures
ValidationError	400	Request validation failures
NotFoundError	404	Resource not found
EsimProviderError	—	Classified eSIM provider failure thrown by adapters (code + optional externalOrderId) — internal to the fulfillment pipeline, never an HTTP envelope
ActivationError	422	SIM activation failures
PaymentError	402/409	Payment processing failures
OperatorError	502/504	Operator API failures