Core Concepts

Overview

Arky is a modular backend platform that provides essential business functionality through a unified API. Understanding these core concepts will help you build effectively with the SDK.

Business

A Business is the top-level entity in Arky. Everything—products, reservations, content, users—belongs to a business.

// Get current business
const business = await sdk.business.getBusiness({
  businessId: 'biz_abc123'
});

Business Hierarchy

Businesses can have parent-child relationships, enabling:

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

// Get parent businesses
const parents = await sdk.business.getBusinessParents({
  businessId: 'child_biz_id'
});

Modules

Arky is organized into domain-specific modules:

Module	Purpose
User	Authentication, profiles, permissions
Business	Settings, subscriptions, team management
E-shop	Products, orders, checkout
Reservation	Services, providers, bookings
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-business search
Location	Geographic data

Resources

Most Arky entities follow a consistent pattern:

// Create
const product = await sdk.eshop.createProduct({
  businessId: 'biz_123',
  name: 'Widget',
  price: 1999 // cents
});

// Read
const product = await sdk.eshop.getProduct({
  businessId: 'biz_123',
  id: 'prod_abc'
});

// Update
await sdk.eshop.updateProduct({
  businessId: 'biz_123',
  id: 'prod_abc',
  name: 'Updated Widget'
});

// Delete
await sdk.eshop.deleteProduct({
  businessId: 'biz_123',
  id: 'prod_abc'
});

// List
const products = await sdk.eshop.getProducts({
  businessId: 'biz_123',
  cursor: null,
  limit: 20
});

Pagination

List endpoints use cursor-based pagination:

let cursor = null;
const allProducts = [];

do {
  const result = await sdk.eshop.getProducts({
    businessId: 'biz_123',
    cursor,
    limit: 50
  });

  if (result.ok) {
    allProducts.push(...result.val.items);
    cursor = result.val.cursor;
  }
} while (cursor);

Identifiers

Arky uses prefixed IDs for clarity:

Prefix	Entity
biz_	Business
usr_	User
prod_	Product
ord_	Order
res_	Reservation
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.createProduct({
  businessId: 'biz_123',
  name: 'Premium Widget',
  slug: 'premium-widget'
});

// Fetch by slug
const product = await sdk.eshop.getProduct({
  businessId: 'biz_123',
  slug: 'premium-widget'
});

Timestamps

All timestamps are Unix timestamps in seconds:

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

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

Money

All monetary values are in minor units (cents):

// Create a $19.99 product
await sdk.eshop.createProduct({
  businessId: 'biz_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.getProduct({
  businessId: 'biz_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 can edit products
const user = await sdk.user.getMe({});
const canEdit = user.val.permissions.includes('products:write');

Permission Scopes

Scope	Description
products:read	View products
products:write	Create/edit products
orders:read	View orders
orders:write	Process orders
reservations:read	View reservations
reservations:write	Manage reservations
content:read	View CMS content
content:write	Edit CMS content
users:read	View users
users:write	Manage users
settings:write	Modify business settings

Webhooks

Receive real-time updates when events occur:

// Configure webhook in business settings
await sdk.business.updateBusiness({
  id: 'biz_123',
  webhookUrl: 'https://yourapp.com/webhooks/arky',
  webhookEvents: [
    'order.created',
    'order.paid',
    'reservation.created',
    'reservation.confirmed'
  ]
});

See Webhooks Guide for complete documentation.

Next Steps

• E-commerce Guide - Build a storefront
• Booking Guide - Create a reservation system
• API Reference - Explore all endpoints