Core Concepts

Overview

Arky is a modular backend platform that provides essential store functionality through a unified API. Storefronts usually use createArkyStore, a framework-agnostic reactive layer over the lower-level SDK.

import { createArkyStore } from 'arky-sdk/storefront-store';

const arkyStore = createArkyStore({
  baseUrl: 'https://api.arky.io',
  storeId: 'store_abc123',
  market: 'us',
  locale: 'en',
});

Store

A Store is the top-level entity in Arky. Everything—products, scheduled services, content, users—belongs to a store.

const store = await arkyStore.store.getStore();

Store Hierarchy

Stores can have parent-child relationships, enabling:

• Multi-location setups
• Franchise models
• White-label solutions

const store = await arkyStore.store.getStore();

Modules

Arky is organized into domain-specific modules:

Module	Purpose
User	Authentication, profiles, permissions
Store	Settings, subscriptions, team management
E-shop	Products, services, providers, orders, checkout
CMS	Content nodes and blocks
Media	File uploads, image management
Notification	Email, SMS, push notifications
Analytics	Metrics, reporting
Promo Codes	Discounts, campaigns
Roles	Permissions, access control
Database	Key-value storage
Network	Cross-store search
Location	Geographic data

Resources

Most Arky entities follow a consistent pattern:

// Read
const product = await arkyStore.eshop.product.loadDetail({
  id: 'prod_abc'
});

// List
const products = await arkyStore.eshop.product.list({
  cursor: null,
  limit: 20
});

// Cart-backed checkout
await arkyStore.eshop.cart.addProduct(product, product.variants[0], 1);
const quote = await arkyStore.eshop.cart.quote();
const order = await arkyStore.eshop.cart.checkout({
  payment_method_id: 'cash'
});

Pagination

List endpoints use cursor-based pagination:

let cursor = null;
const allProducts = [];

do {
  const result = await arkyStore.eshop.product.list({
    cursor,
    limit: 50
  });

  allProducts.push(...result.items);
  cursor = result.cursor;
} while (cursor);

Identifiers

Arky uses prefixed IDs for clarity:

Prefix	Entity
store_	Store
usr_	User
prod_	Product
ord_	Order
svc_	Service
prv_	Provider
node_	CMS Node
media_	Media file
role_	Role
promo_	Promo code

Slugs

Many resources support slugs for SEO-friendly URLs:

// Create with slug
await sdk.eshop.product.create({
  key: 'premium-widget',
  slug: { en: 'premium-widget' },
  variants: []
});

// Fetch by slug
const product = await arkyStore.eshop.product.loadDetail({
  slug: 'premium-widget'
});

Timestamps

All timestamps are Unix timestamps in seconds:

const product = await sdk.eshop.product.get({ storeId, id });

console.log(product.val.created_at); // 1704067200
console.log(new Date(product.val.created_at * 1000)); // 2024-01-01T00:00:00.000Z

Money

All monetary values are in minor units (cents):

// Create a $19.99 product
await sdk.eshop.product.create({
  storeId: 'store_123',
  name: 'Widget',
  price: 1999 // $19.99
});

// Display formatted price
import { formatPrice } from 'arky-sdk/utils';

const display = formatPrice(1999, 'USD'); // "$19.99"

Result Type

All SDK methods return a Result type for explicit error handling:

const result = await sdk.eshop.product.get({
  storeId: 'store_123',
  id: 'prod_abc'
});

if (result.ok) {
  // Success - access data
  const product = result.val;
  console.log(product.name);
} else {
  // Error - handle failure
  const error = result.val;
  console.error(error.message);
}

Pattern Matching

import { match } from 'ts-results-es';

const productName = match(result)
  .ok(product => product.name)
  .err(error => 'Unknown Product')
  .value;

Permissions

Access is controlled through roles and permissions:

// Check if user has admin role for a store
const user = await sdk.account.getMe({});
const membership = user.memberships?.find(m => m.store_id === 'store_123');
const isAdmin = membership?.role === 'Admin' || membership?.role === 'Owner';

Permission Scopes

Scope	Description
products:read	View products
products:write	Create/edit products
orders:read	View orders
orders:write	Process orders
services:read	View services and providers
services:write	Manage services and providers
content:read	View CMS content
content:write	Edit CMS content
users:read	View users
users:write	Manage users
settings:write	Modify store settings

Webhooks

Receive real-time updates when events occur:

// Configure webhook in store settings
await sdk.store.updateStore({
  id: 'store_123',
  webhook_url: 'https://yourapp.com/webhooks/arky',
  webhook_events: [
    'order.created',
    'order.payment_received',
    'order.reminder'
  ]
});

See Webhooks Guide for complete documentation.

Next Steps

• E-commerce Guide - Build a storefront
• Scheduled Services Guide - Create a service scheduling flow
• API Reference - Explore all endpoints