@arcubase/hooklets

SDK for third-party integrations in carthooks iframe environment.

Installation

npm install @arcubase/hooklets

Usage

Basic Setup

import { Frame } from '@arcubase/frame-ts';

// Initialize the SDK
const sdk = new Frame();
const { token, locale, timezone, darkMode } = await sdk.init();

// Use the token for backend API calls
const response = await fetch('/api/exchange-token', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` }
});

Get Collections and Data

// Get all available collections
const collections = await sdk.getCollections();

// Get specific collection
const collection = await sdk.getCollection('collection-id');

// Get current user info
const user = await sdk.getUser();

Handle Connection Events

// Listen for successful connection creation
sdk.onSuccess((connectionId) => {
  console.log('Connection created:', connectionId);
  sdk.close(); // Close the iframe
});

// Listen for errors
sdk.onError((error) => {
  console.error('Connection failed:', error);
});

// Notify success
sdk.notifySuccess('connection-123');

// Notify error
sdk.notifyError('Failed to create connection');

URL Parameters

The SDK automatically reads these URL parameters:

• token: Authentication token (required)
• lc: User locale (default: 'en-US')
• tz: User timezone (default: 'UTC')
• dark: Dark mode enabled (default: false)

Example URL: https://your-app.com/integration?token=abc123&lc=zh-CN&tz=Asia/Shanghai&dark=1

API Reference

Hooklets Class

Methods

• init(): Initialize the SDK with URL parameters
• getToken(): Get authentication token
• getLocale(): Get user locale
• getTimezone(): Get user timezone
• isDarkMode(): Check if dark mode is enabled
• getCollections(): Get all available collections
• getCollection(id): Get specific collection by ID
• getUser(): Get current user information
• onSuccess(callback): Register success callback
• onError(callback): Register error callback
• onClose(callback): Register close callback
• notifySuccess(connectionId): Notify parent of successful connection
• notifyError(error): Notify parent of connection error
• notifyUpdated(connectionId): Notify parent of connection update
• close(): Close the iframe

Types

See types.ts for complete TypeScript definitions.

Security

• SDK only works within iframe context
• All communication with parent uses postMessage
• Token has limited scope and expiration
• Origin validation is handled by parent application

License

MIT