Quick Start

Quick Start

Get up and running with Arky in 5 minutes. This guide shows you how to initialize the SDK and start fetching data immediately.

Installation

npm install arky-sdk

SDK Initialization Patterns

Pattern 1: Client-Side with Guest Token (Browsing Products/Services)

Perfect for public data like product listings, service browsing, and CMS content.

import { createArkySDK } from 'arky-sdk';

const sdk = createArkySDK({
  baseUrl: 'https://api.arky.io',
  businessId: 'your-business-id',
  market: 'us',
  storageUrl: 'https://storage.arky.io',

  autoGuest: true, // Automatically creates guest token on first request

  getToken: () => ({
    accessToken: localStorage.getItem('accessToken') || '',
    refreshToken: localStorage.getItem('refreshToken') || '',
    provider: 'GUEST',
    expiresAt: parseInt(localStorage.getItem('expiresAt') || '0'),
  }),

  setToken: (tokens) => {
    localStorage.setItem('accessToken', tokens.accessToken);
    if (tokens.refreshToken) localStorage.setItem('refreshToken', tokens.refreshToken);
    if (tokens.expiresAt) localStorage.setItem('expiresAt', tokens.expiresAt.toString());
  },

  logout: () => {
    localStorage.removeItem('accessToken');
    localStorage.removeItem('refreshToken');
    localStorage.removeItem('expiresAt');
  },
});

// Now you can fetch data immediately
const { items: products } = await sdk.eshop.getProducts({ status: 'ACTIVE', limit: 20 });

Pattern 2: Server-Side with API Key (SSR in Astro/Next.js)

For server-side rendering where you need to fetch data at build time or on request.

// In Astro, Next.js, or other SSR environments
import { createArkySDK } from 'arky-sdk';

const sdk = createArkySDK({
  baseUrl: 'https://api.arky.io',
  businessId: 'your-business-id',
  market: 'us',
  storageUrl: 'https://storage.arky.io',

  autoGuest: false, // Don't create guest tokens on server

  getToken: () => ({
    accessToken: process.env.ARKY_API_KEY || '', // Server API key
    provider: 'API',
    expiresAt: 0,
  }),

  setToken: () => {}, // No-op on server
  logout: () => {},
});

// Fetch CMS content for SSR
const collection = await sdk.cms.getCollection({ id: 'website' });
const { items: posts } = await sdk.cms.getCollectionEntries({ collectionId: 'blog', limit: 10 });

Pattern 3: Authenticated User (Checkout, Bookings, Account Management)

After user logs in, attach their auth token to enable protected operations.

const sdk = createArkySDK({
  baseUrl: 'https://api.arky.io',
  businessId: 'your-business-id',
  market: 'us',
  autoGuest: false, // We'll handle auth manually

  getToken: () => ({
    accessToken: localStorage.getItem('userToken') || '',
    refreshToken: localStorage.getItem('refreshToken') || '',
    provider: 'EMAIL', // or 'GOOGLE'
    expiresAt: parseInt(localStorage.getItem('expiresAt') || '0'),
  }),

  setToken: (tokens) => {
    localStorage.setItem('userToken', tokens.accessToken);
    if (tokens.refreshToken) localStorage.setItem('refreshToken', tokens.refreshToken);
    if (tokens.expiresAt) localStorage.setItem('expiresAt', tokens.expiresAt.toString());
  },

  logout: () => {
    localStorage.clear();
    window.location.href = '/login';
  },
});

// Login first
const auth = await sdk.user.loginUser({
  email: '[email protected]',
  password: 'password',
  provider: 'EMAIL',
});
// Tokens automatically stored via setToken

// Now you can do protected operations
const user = await sdk.user.getMe({});
const result = await sdk.eshop.checkout({ items: cartItems, paymentMethod: 'CREDIT_CARD' });

Make Your First Request

Fetch Business Information

SDKHTTP

// Using the SDK
const business = await sdk.business.getBusiness({});
console.log('Business name:', business.name);
console.log('Markets:', business.configs.markets);

Fetch CMS Content

SDKHTTP

// Get a collection (e.g., blog posts)
const collection = await sdk.cms.getCollection({ id: 'blog' });

// Get entries from the collection
const { items: posts } = await sdk.cms.getCollectionEntries({
  collectionId: 'blog',
  limit: 10,
});

posts.forEach(post => {
  const title = sdk.utils.getBlockTextValue(
    post.blocks.find(b => b.key === 'title'),
    'en' // locale
  );
  console.log('Post:', title);
});

Fetch Products

SDKHTTP

// List products
const { items: products } = await sdk.eshop.getProducts({
  status: 'ACTIVE',
  limit: 20,
});

products.forEach(product => {
  const price = sdk.utils.getMarketPrice(
    product.variants[0].prices,
    'us' // market code lowercase
  );
  console.log(`${product.name}: ${price}`);
});

Framework Support

Arky works with any JavaScript/TypeScript framework:

• React / Next.js
• Vue / Nuxt
• Svelte / SvelteKit
• Astro
• Angular
• Vanilla JS/TS
• Node.js / Express / Fastify
• Any other JavaScript environment

The SDK is framework-agnostic - just import and use it.

Authentication Strategies

Guest Mode (Public Data)

Enable autoGuest: true (default) to automatically create a guest token for unauthenticated requests:

const sdk = createArkySDK({
  autoGuest: true,
  // ... other config
});
// Guest token is auto-created on first request

Email & Password

// Register a new user
const user = await sdk.user.registerUser({
  name: 'John Doe',
  email: '[email protected]',
  password: 'securePassword123',
});

// Login
const tokens = await sdk.user.loginUser({
  email: '[email protected]',
  password: 'securePassword123',
  provider: 'EMAIL',
});

// Store tokens
sdk.setToken(tokens);

OAuth (Google)

// Get OAuth URL
const { url } = await sdk.user.getLoginUrl({
  provider: 'GOOGLE',
  originUrl: window.location.origin,
  redirectUrl: `${window.location.origin}/auth/callback`,
});

// Redirect user to Google
window.location.href = url;

// On callback page, exchange code for tokens
const tokens = await sdk.user.loginUser({
  provider: 'GOOGLE',
  code: urlParams.get('code'),
  originUrl: window.location.origin,
});

sdk.setToken(tokens);

API Keys (Server-Side)

For server-side or backend integrations, use API keys:

const sdk = createArkySDK({
  baseUrl: 'https://api.arky.io',
  businessId: 'your-business-id',
  market: 'US',
  getToken: async () => ({
    accessToken: process.env.ARKY_API_KEY,
    provider: 'API', // Important: signals X-API-Key header usage
  }),
  setToken: () => {}, // No-op for API keys
  logout: () => {},
  autoGuest: false,
});

Next Steps

• Core Concepts: Understand Businesses, Markets, Blocks, and more
• Business API: Manage business settings and configuration
• CMS API: Work with collections and entries
• E-shop API: Build your storefront
• SDK Guide: Advanced SDK usage and utilities