@ossy/sdk

API client for Ossy services. Use with @ossy/sdk-react for React hooks.

Installation

npm install @ossy/sdk @ossy/sdk-react

Quick start

import { SDK } from '@ossy/sdk'

const sdk = SDK.of({
  workspaceId: 'your-workspace-id',
  apiUrl: '/api/v0', // optional, this is the default (same origin)
})

// List resources in a folder
const resources = await sdk.resources.list({ location: '/docs' })

// Get a single resource
const resource = await sdk.resources.get({ id: 'resource-id' })

Configuration

| Option | Description | |--------|-------------| | workspaceId | Your workspace identifier (required for most operations) | | apiUrl | API base URL (default: /api/v0, same origin). CLI / Node clients without a page origin should use https://ossy.se/api/v0. | | authorization | Bearer token for authenticated requests |

API overview

Workspaces

• sdk.workspaces.current() — Get current workspace
• sdk.workspaces.list() — List workspaces
• sdk.workspaces.get({ workspaceId }) — Get workspace by ID
• sdk.workspaces.create(payload) — Create workspace
• sdk.workspaces.importSchemas(...) — Import schemas
• sdk.workspaces.getSchemas(...) — Get schemas

Resources

• sdk.resources.list({ location }) — List resources in folder
• sdk.resources.get({ id }) — Get resource by ID
• sdk.resources.create(payload) — Create resource
• sdk.resources.search(query) — Search resources
• sdk.resources.remove({ id }) — Delete resource
• sdk.resources.updateContent(...) — Update resource content
• sdk.resources.move(...) — Move resource
• sdk.resources.rename(...) — Rename resource
• sdk.resources.upload({ location, file }) — Upload file

Auth

• sdk.auth.signIn(payload) — Sign in
• sdk.auth.signOff() — Sign off
• sdk.auth.getAuthenticatedUser() — Get current user

Current user

• sdk.currentUser.get() — Get current user
• sdk.currentUser.update(payload) — Update user
• sdk.currentUser.history() — Get user history

With React

Use @ossy/sdk-react for WorkspaceProvider and useSdk(). Domain hooks (useResources, useAuthentication, …) live in feature packages — see @ossy/sdk-react README.

import { ReactSdk, WorkspaceProvider } from '@ossy/sdk-react'
import { AuthenticationProvider } from '@ossy/authentication'

const sdk = ReactSdk.of({ workspaceId: 'your-workspace-id' })

export const App = () => (
  <WorkspaceProvider sdk={sdk}>
    <AuthenticationProvider>
      <YourApp />
    </AuthenticationProvider>
  </WorkspaceProvider>
)

Agents (MCP)

MCP is embedded in the app server — same actions as sdk.invoke, exposed as tools from build/capabilities.json.

{
  "mcpServers": {
    "ossy-local": {
      "url": "http://localhost:3006/mcp",
      "headers": {
        "Authorization": "Bearer your-jwt-token",
        "workspaceId": "your-workspace-id"
      }
    }
  }
}

See TODO-AGENT-MCP.md.

Environments

sdk.invoke is the task API in every environment. The object behind it is not the same implementation.

| Environment | Implementation | | --- | --- | | Browser and CLI | @ossy/sdk posts POST /actions. The session is the actor. sdk.resources.get / list / create hit those same actions. | | Server task | createInProcessSdk runs ActionService.invoke in-process. An HTTP action forwards the caller's req, and nested invokes keep that actor. withEventContext and forWorkspace bind the bot to one workspace. A global cron runs once per workspace the bot belongs to. |

A task that needs a resource command uses sdk.invoke (GetResource, ListResources, CreateResource, PatchResourceContent, …). The resource action folds through ResourceStream with the actor from that request. @ossy/resources/server does not export ResourceStream; feature tasks must not import the fold. See packages/resources/SPEC.md and #988.

Invoking platform actions

Writes and commands use sdk.invoke(action, payload) with a platform action POJO or id string:

import { SDK } from '@ossy/sdk'
import { BookingCreate } from '@ossy/booking'

const sdk = SDK.of({ workspaceId: 'your-workspace-id' })

// POJO (preferred) — importable on client and server
await sdk.invoke(BookingCreate, { providerId, startAt, duration })
// HTTP: POST /actions with { action: '@ossy/booking/actions/create', payload: { … } }

Reads use location paths — not invoke:

await sdk.resources.list({ location: '/@ossy/booking/services/' })

Push invalidation (ADR 0008)

Subscribe to workspace SSE events at GET /events to invalidate client read caches when server state changes.

import { SDK } from '@ossy/sdk'

const sdk = SDK.of({ workspaceId: 'your-workspace-id' })

const unsubscribe = sdk.subscribePush({
  onMessage: (message) => {
    // message.invalidate — cache keys to drop (when present)
    console.log(message.kind, message.invalidate)
  },
  onError: (error) => {
    console.error('SSE error', error)
  },
})

// later
unsubscribe()

PushMessage fields include kind, type, resourceId, event, version, eventId, scope.workspaceId, and invalidate (string array of cache keys).

Requires workspaceId on the SDK config, or a workspace cookie on the same origin. Returns a no-op unsubscribe when EventSource is unavailable (SSR/tests).

With React, mount PushInvalidationSubscriber from @ossy/sdk-react on pages that need live invalidation, or set enablePushInvalidation: true in app config (off by default).