npm package: @orgosync/sdk
Description: Orgo Sync SDK — Real-time scheduling intelligence for sports platforms
Latest version: 1.0.0

# @orgosync/sdk

The official Orgo Sync SDK. Real-time scheduling intelligence for sports platforms.

Replace your ICS link with a secure, real-time API. Three lines of code. One afternoon.

## Install

```bash
npm install @orgosync/sdk
```

## Quick Start

```typescript
import { OrgoSync } from "@orgosync/sdk";

const orgo = new OrgoSync({ apiKey: "sk_live_xxx" });
await orgo.publish({
  events: [{
    action: "created",
    source: "json",
    payload: yourScheduleData,
  }],
});
```

## API

### `new OrgoSync(options)`

| Option    | Type     | Required | Description                                  |
| --------- | -------- | -------- | -------------------------------------------- |
| `apiKey`  | `string` | Yes      | Your API key (`sk_live_*` or `sk_test_*`)    |
| `baseUrl` | `string` | No       | API base URL (defaults to `https://api.orgosync.com`) |

### Core Methods

#### `orgo.publish(input)` → `Promise<PublishResponse>`

Publish schedule events. Subscribers are notified via webhook in real-time.

```typescript
const result = await orgo.publish({
  events: [{
    action: "created",
    source: "json",
    payload: {
      title: "U12 Soccer vs Eagles",
      start: "2026-04-05T10:00:00-05:00",
      end: "2026-04-05T11:30:00-05:00",
      location: "Riverside Athletic Complex",
    },
  }],
});
// → { accepted: true, event_count: 1, subscribers_notified: 3, request_id: "..." }
```

#### `orgo.enrich(input)` → `Promise<EnrichResponse>`

Enrich a single event with geocoding, drive time, weather, timeline, and conflict detection.

```typescript
const result = await orgo.enrich({
  title: "U12 Soccer vs Eagles",
  start: "2026-04-05T10:00:00-05:00",
  end: "2026-04-05T11:30:00-05:00",
  location: "Riverside Athletic Complex, Austin TX",
  origin: { address: "456 Elm St, Austin TX" },
});

console.log(result.data.enrichment.timeline.depart_by);
console.log(result.data.enrichment.weather?.at_event_start.condition);
```

#### `orgo.ingest(input)` → `Promise<EnrichResponse | BatchJobResponse>`

Ingest native JSON from a platform adapter (TeamSnap, ICS, raw JSON) and optionally enrich.

#### `orgo.enrichBatch(input)` → `Promise<BatchJobResponse>`

Enrich up to 50 events asynchronously. Returns a job ID for polling.

#### `orgo.parse(ics)` → `Promise<ParseResponse>`

Parse an ICS/iCal string into Orgo Canonical Events.

#### `orgo.status(jobId)` → `Promise<JobStatusResponse>`

Check the status of an async batch enrichment job.

### Webhook Subscriptions

#### `orgo.createSubscription(input)` → `Promise<SubscriptionCreateResponse>`

Create a webhook subscription to receive real-time event notifications.

```typescript
const sub = await orgo.createSubscription({
  publisher_id: "partner-uuid",
  endpoint_url: "https://myapp.com/webhooks/orgo",
  event_filters: ["event.created", "event.updated"],
});
console.log(sub.signing_secret); // use this to verify webhook signatures
```

#### `orgo.listSubscriptions()` → `Promise<SubscriptionListResponse>`

#### `orgo.getSubscription(id)` → `Promise<SubscriptionDetailResponse>`

#### `orgo.updateSubscription(id, input)` → `Promise<WebhookSubscription>`

#### `orgo.deleteSubscription(id)` → `Promise<void>`

#### `orgo.testSubscription(id)` → `Promise<{ success, delivery_id, message }>`

### Calendar Feeds

#### `orgo.createFeed(options)` → `Promise<CreateFeedResponse>`

Create a real-time calendar feed consumers can subscribe to.

#### `orgo.pushToFeed(feedId, events)` → `Promise<PushToFeedResponse>`

Push events to an existing feed.

## Sandbox Mode

Use `sk_test_*` keys for development. Sandbox requests return instant mock responses without consuming API credits.

## Error Handling

```typescript
import { OrgoSync, OrgoSyncError } from "@orgosync/sdk";

try {
  await orgo.publish({ events: [/* ... */] });
} catch (error) {
  if (error instanceof OrgoSyncError) {
    console.error(error.code);       // e.g. "VALIDATION_ERROR"
    console.error(error.message);    // human-readable message
    console.error(error.statusCode); // HTTP status code
    console.error(error.details);    // additional context
  }
}
```

## TypeScript

The SDK ships with full TypeScript declarations. All request/response types are exported:

```typescript
import type {
  CanonicalEvent,
  PublishRequest,
  EnrichResponse,
  WebhookSubscription,
  OutboundWebhookPayload,
} from "@orgosync/sdk";
```

## License

MIT