Core Types

Core types used throughout the Arky SDK.

Result Type

All SDK methods return a Result type:

type Result<T, E> = Ok<T> | Err<E>;

interface Ok<T> {
  ok: true;
  val: T;
}

interface Err<E> {
  ok: false;
  val: E;
}

Usage

const result = await sdk.eshop.getProduct({ businessId, id });

if (result.ok) {
  const product = result.val; // T
} else {
  const error = result.val;   // ApiError
}

ApiError

interface ApiError {
  error: string;
  message: string;
  statusCode: number;
  details?: {
    field?: string;
    reason?: string;
    [key: string]: unknown;
  };
}

Pagination

PaginatedResponse

interface PaginatedResponse<T> {
  items: T[];
  cursor: string | null;
  hasMore: boolean;
}

PaginationParams

interface PaginationParams {
  cursor?: string | null;
  limit?: number;
}

User

interface User {
  id: string;
  email: string;
  firstName?: string;
  lastName?: string;
  phone?: string;
  avatar?: string;
  provider: AuthProvider;
  confirmed: boolean;
  createdAt: number;
  updatedAt: number;
  permissions?: string[];
}

type AuthProvider = 'EMAIL' | 'GOOGLE' | 'APPLE' | 'GUEST';

Business

interface Business {
  id: string;
  key: string;
  timezone: string;
  languages: Language[];
  emails: BusinessEmails;
  subscription?: Subscription;
  counts?: Record<string, number>;
}

interface Market {
  id: string;
  businessId: string;
  key: string;
  currency: string;
  taxMode: 'exclusive' | 'inclusive';
  paymentMethods: PaymentMethod[];
  zones: Zone[];
  createdAt: number;
  updatedAt: number;
}

interface BusinessEmails {
  billing: string;
  support: string;
}

Address

interface Address {
  name: string;
  company?: string | null;
  street1: string;
  street2?: string | null;
  city: string;
  state: string;
  postalCode: string;
  country: string;
  phone?: string | null;
  email?: string | null;
}

Customer

interface Customer {
  id: string;
  businessId: string;
  emails: string[];
  status: 'active' | 'archived';
  promoUsage: PromoUsage[];
  blocks: Block[];
  taxonomies: TaxonomyEntry[];
  authTokens: CustomerAuthToken[];
  verificationCodes: CustomerVerificationCode[];
  audienceSubscriptions: any[];
  reactions: any[];
  createdAt: number;
  updatedAt: number;
}

Media

interface Media {
  id: string;
  resolutions: { [key: string]: MediaResolution };
  mimeType: string;
  title?: string | null;
  description?: string | null;
  alt?: string | null;
  entity: string;
  metadata?: string | null;
  uploadedAt: string;
  slug: Record<string, string>;
}

interface MediaResolution {
  id: string;
  size: string;
  url: string;
}

Timestamps

All timestamps in Arky are Unix timestamps (seconds since epoch):

// Server response
{
  createdAt: 1704067200,  // Jan 1, 2024 00:00:00 UTC
  updatedAt: 1704153600   // Jan 2, 2024 00:00:00 UTC
}

// Convert to Date
const date = new Date(timestamp * 1000);

// Convert from Date
const timestamp = Math.floor(date.getTime() / 1000);

Money

All monetary values are in minor units (cents):

// Stored as cents
{
  price: 1999,           // $19.99
  compareAtPrice: 2999,  // $29.99
  total: 5497            // $54.97
}

// Convert for display
const dollars = cents / 100;  // 19.99

Status Types

Common Status

Most entities (Node, Product, Service, Provider, Booking, Order, …) share the same active/archived shape:

type Status = 'active' | 'archived';

Order Status

Orders have both an active/archived status and a separate lifecycle workflowStatus:

type OrderStatus = Status;       // 'active' | 'archived'

type OrderWorkflowStatus =
  | 'created'
  | 'pending'
  | 'authorized'
  | 'confirmed'
  | 'shipped'
  | 'completed'
  | 'cancelled'
  | 'failed';

Booking Status

type BookingStatus = Status;     // 'active' | 'archived'

type BookingWorkflowStatus =
  | 'created'
  | 'pending'
  | 'authorized'
  | 'confirmed'
  | 'completed'
  | 'cancelled'
  | 'failed';

Subscription Status

type SubscriptionStatus =
  | 'pending'
  | 'active'
  | 'cancellation_scheduled'
  | 'cancelled'
  | 'expired';

SDK Configuration

interface ArkyClientConfig {
  businessId: string;
  environment?: 'production' | 'sandbox';
  baseUrl?: string;
  getToken: () => string | null;
  setToken: (token: string) => void;
  onAuthError?: () => void;
}