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.product.get({ store_id: storeId, id });

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

ApiError

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

Pagination

PaginatedResponse

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

PaginationParams

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

User

interface User {
  id: string;
  email: string;
  first_name?: string;
  last_name?: string;
  phone?: string;
  avatar?: string;
  provider: AuthProvider;
  confirmed: boolean;
  created_at: number;
  updated_at: number;
  permissions?: string[];
}

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

Store

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

interface Market {
  id: string;
  store_id: string;
  key: string;
  currency: string;
  tax_mode: 'exclusive' | 'inclusive';
  payment_methods: PaymentMethod[];
  zones: Zone[];
  created_at: number;
  updated_at: number;
}

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

Address

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

Profile

interface Profile {
  id: string;
  store_id: string;
  email: string | null;
  verified: boolean;
  status: 'active' | 'archived';
  promo_usage: PromoUsage[];
  taxonomies: TaxonomyEntry[];
  auth_tokens: ProfileAuthToken[];
  verification_codes: ProfileVerificationCode[];
  created_at: number;
  updated_at: number;
}

Media

interface Media {
  id: string;
  resolutions: { [key: string]: MediaResolution };
  mime_type: string;
  title?: string | null;
  description?: string | null;
  alt?: string | null;
  entity: string;
  metadata?: string | null;
  created_at: number;
  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
{
  created_at: 1704067200,  // Jan 1, 2024 00:00:00 UTC
  updated_at: 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
  compare_at_price: 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, Order, …) share the same active/archived shape:

type Status = 'active' | 'archived';

Order Status

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

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

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

Subscription Status

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

SDK Configuration

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