@orbixdocs/sdk

Universal Component & Block SDK for Orbix OS — Build stunning, collaborative, and AI-powered interactive blocks and widgets.

📦 Installation

npm install @orbixdocs/sdk
# or
pnpm add @orbixdocs/sdk
# or
yarn add @orbixdocs/sdk

🚀 Quick Start: Creating a Custom Block

import React from 'react';
import { defineBlock, useOrbixState, useOrbixAI } from '@orbixdocs/sdk';
import { Sparkles, Heart } from 'lucide-react';

// 1. Define Block Component
export const QuickPollerBlock = (props: any) => {
  // 1-line real-time synchronized state across Yjs & IndexedDB
  const [poll, setPoll] = useOrbixState(props, {
    question: 'Should we launch Orbix SDK today?',
    upvotes: 0
  });

  // Embedded block-level AI streaming
  const { generate, isGenerating } = useOrbixAI();

  const handleAiIdea = async () => {
    const suggestion = await generate('Suggest a fun poll question for a team meeting:');
    if (suggestion) setPoll({ ...poll, question: suggestion.trim() });
  };

  return (
    <div className="p-4 rounded-xl bg-[#101010] border border-white/[0.08] text-white">
      <h3 className="font-semibold text-sm mb-2">{poll.question}</h3>
      <div className="flex items-center gap-3">
        <button
          onClick={() => setPoll({ ...poll, upvotes: poll.upvotes + 1 })}
          className="flex items-center gap-1.5 px-3 py-1.5 bg-white text-black font-semibold rounded-lg text-xs"
        >
          <Heart size={14} className="text-red-500 fill-red-500" />
          <span>{poll.upvotes} Upvotes</span>
        </button>
        <button
          onClick={handleAiIdea}
          disabled={isGenerating}
          className="flex items-center gap-1.5 px-3 py-1.5 bg-[#181818] border border-white/[0.08] text-xs text-gray-300 rounded-lg"
        >
          <Sparkles size={13} className="text-amber-400" />
          <span>{isGenerating ? 'Thinking...' : 'AI Suggest'}</span>
        </button>
      </div>
    </div>
  );
};

// 2. Export Contract
export default defineBlock({
  manifest: {
    id: 'com.orbix.quick-poller',
    name: 'Quick Poller',
    version: '1.0.0',
    category: 'Interactive',
    description: 'Interactive real-time polling widget with AI question ideas.',
    icon: '📊'
  },
  component: QuickPollerBlock
});

🛠️ Core SDK Features

1. useOrbixState(props, initial)

Universal 1-line real-time state synchronization that automatically distributes state mutations across Yjs CRDTs, IndexedDB offline cache, and the cloud.

const [state, setState] = useOrbixState(props, { count: 0, title: '' });
setState({ count: state.count + 1 });

2. useOrbixAI(options)

Embedded block-level LLM streaming and generation.

const { generate, stream, isGenerating, error } = useOrbixAI({
  systemPrompt: 'You are a concise data analyst.'
});

const summary = await generate('Analyze these metrics: ' + JSON.stringify(data));

3. useOrbixDocument() & useOrbixDatabase()

Direct programmatic access to the host document AST and relational databases.

const { pageTitle, blockCount, appendBlock } = useOrbixDocument();
const { records, query, addRecord, updateRecord } = useOrbixDatabase();

4. Reactive Block Graph (useBlockInput, useBlockOutput, useBlockEvent)

Connect independent blocks in reactive event pipelines.

const input = useBlockInput('metrics_in');
const emit = useBlockOutput('filtered_out');
useBlockEvent('data_updated', (payload) => { ... });

5. Granular RBAC (useBlockPermissions, <PermissionGuard>)

Role-based access control (Host, Admin, Editor, Member, Guest).

const { isAdmin, hasPermission } = useBlockPermissions(props);

<PermissionGuard permission="ADMINISTRATOR" fallback={<p>Admin only</p>}>
  <AdminConfigPanel />
</PermissionGuard>

6. Secrets Vault (useOrbixEnv)

Secure per-block environment variable and API key storage.

const { OPENWEATHER_API_KEY, GITHUB_TOKEN } = useOrbixEnv(props);

7. Tiered Offline Storage (usePersistentStorage, useCache)

const [value, setValue] = usePersistentStorage('my_key', defaultValue);

📄 License

MIT © Orbix OS