Orbita SDK

The Orbita SDK is a powerful and easy-to-use JavaScript client library designed to simplify interaction with the Orbita app's REST and WebSocket APIs. By encapsulating authentication, state management, data fetching, and event handling into intuitive methods, it significantly reduces boilerplate code in your projects. Whether you're building a Node.js backend service or a modern web frontend with frameworks like React and Next.js, the Orbita SDK helps you get up and running in minutes with minimal configuration. Dive in to explore streamlined API calls, automatic retry logic, built-in TypeScript support, and comprehensive documentation that will accelerate your development workflow and ensure best practices out of the box.

Installation

npm install orbita-sdk
# or
yarn add orbita-sdk
# or
pnpm add orbita-sdk

Types

Item

The Item type is used for multi-item checkout flows:

export interface Item {
  itemName: string;
  itemPriceAmount: string;
  itemPriceCurrency: string;
  itemQuantity: number;
}

Usage with Next.js

The SDK is designed to work well with Next.js applications. Here's how to use it properly:

Client-Side Only Components

For client-side checkout buttons, use the 'use client' directive:

"use client";

import { handleBasicCheckout } from "orbita-sdk";

export default function CheckoutButton() {
  const initiateCheckout = () => {
    handleBasicCheckout("your-payment-id", "https://your-return-url.com");
  };

  return <button onClick={initiateCheckout}>Checkout with Orbita</button>;
}

Server Components

To use signature creation on the server side:

// app/api/create-signature/route.ts
import { createSignature } from "orbita-sdk";
import { NextResponse } from "next/server";

export async function POST(request: Request) {
  const { message } = await request.json();

  // Get your private key from environment variables
  const privateKey = process.env.ORBITA_PRIVATE_KEY || "";

  try {
    const signature = await createSignature(message, privateKey);
    return NextResponse.json({ signature });
  } catch (error) {
    return NextResponse.json(
      { error: "Signature creation failed" },
      { status: 500 }
    );
  }
}

Advanced Usage: Multi-Item Checkout

For more complex checkout flows with multiple items:

"use client";

import { handleMultipleItemsBusinessCheckout, Item } from "orbita-sdk";

export default function ProductCheckout() {
  const items: Item[] = [
    {
      itemName: "Premium T-Shirt",
      itemPriceAmount: "2.99",
      itemPriceCurrency: "USD",
      itemQuantity: 2,
    },
    {
      itemName: "Leather Wallet",
      itemPriceAmount: "29.99",
      itemPriceCurrency: "USD",
      itemQuantity: 1,
    },
  ];

  const handleCheckout = async () => {
    try {
      await handleMultipleItemsBusinessCheckout(
        "29", // paymentId (will be sent as a number)
        items,
        "USD",
        "https://your-return-url.com"
        // Optionally, you can specify a custom signature endpoint as the 5th argument
      );
    } catch (error) {
      console.error("Checkout failed:", error);
    }
  };

  return <button onClick={handleCheckout}>Checkout</button>;
}

Signature Endpoint Parameter

• The handleMultipleItemsBusinessCheckout and handleOneItemBusinessCheckout functions accept an optional signatureEndpoint parameter (default: "/api/create-signature").
• This should point to an API route that returns a signature for the payment. For most Next.js apps, the default is sufficient if you implement the server route as shown above.

Single-Item Checkout

"use client";

import { handleOneItemBusinessCheckout } from "orbita-sdk";

export default function SingleProductCheckout() {
  const handleCheckout = async () => {
    try {
      await handleOneItemBusinessCheckout(
        "payment-12345",
        "19.99",
        "USD",
        "https://your-return-url.com"
        // Optionally, you can specify a custom signature endpoint as the 5th argument
      );
    } catch (error) {
      console.error("Checkout failed:", error);
    }
  };

  return <button onClick={handleCheckout}>Checkout</button>;
}

Environment Variables

• The SDK uses the following environment variables (set at build time or via your deployment platform):
  • ORBITA_SAVE_CHECKOUT_DATA_API_ENDPOINT (default: test endpoint)
  • ORBITA_SAVE_CHECKOUT_DATA_API_KEY (default: test key)
  • ORBITA_APP_URL (default: https://testnet.orbita.zone)
• For production, override these with your own values.

Troubleshooting

CORS Issues

If you see network errors or CORS errors in the browser console when using handleMultipleItemsBusinessCheckout, ensure that:

• Your backend/API endpoint responds to OPTIONS preflight requests with the correct CORS headers:
  • Access-Control-Allow-Origin: * (or your domain)
  • Access-Control-Allow-Methods: POST, OPTIONS
  • Access-Control-Allow-Headers: Content-Type, x-api-key
• If you do not control the backend, you may need to proxy requests through your own server.

Environment Variables in Next.js

• In Next.js, only variables prefixed with NEXT_PUBLIC_ are available in the browser. If you override the defaults, ensure you expose them correctly.
• Use console.log to debug values if you see unexpected behavior.

Important Notes for Next.js

• Always use the SDK's checkout functions in client components (with 'use client' directive)
• Handle signature creation on the server side where possible
• The SDK automatically detects browser vs. server environments
• For SSR applications, crypto operations are properly isolated to prevent hydration issues