go-scheduler-node-sdk 1.0.0

package/README.md

@@ -0,0 +1,467 @@
+# Go-Scheduler TypeScript SDK
+
+TypeScript SDK for interacting with the go-scheduler REST API.
+
+## Installation
+
+```bash
+yarn install go-scheduler-node-sdk
+```
+
+or
+
+```bash
+yarn add go-scheduler-node-sdk
+```
+
+## Quick Start
+
+```typescript
+import { SchedulerClient } from "go-scheduler-node-sdk";
+
+const client = new SchedulerClient({
+  baseURL: "http://localhost:8080",
+  timeout: 30000,
+  headers: {
+    "Authorization": "Bearer your-token-here"
+  }
+});
+
+// Check service health
+const health = await client.healthCheck();
+console.log(health);
+```
+
+## Usage Examples
+
+### Calendars
+
+```typescript
+// Create a calendar
+const calendar = await client.calendars.create({
+  account_id: "user123",
+  name: "My Calendar",
+  description: "Personal calendar",
+  timezone: "America/New_York",
+  metadata: { color: "blue" }
+});
+
+// Get a calendar
+const calendar = await client.calendars.get("calendar-uid");
+
+// List calendars
+const calendars = await client.calendars.list(50, 0);
+
+// Update a calendar
+const updated = await client.calendars.update("calendar-uid", {
+  name: "Updated Calendar Name",
+  description: "New description"
+});
+
+// Delete a calendar
+await client.calendars.delete("calendar-uid");
+```
+
+### Events
+
+```typescript
+// Create a single event
+const event = await client.events.create({
+  calendar_uid: "calendar-uid",
+  account_id: "user123",
+  start_ts: Math.floor(Date.now() / 1000) + 3600,
+  end_ts: Math.floor(Date.now() / 1000) + 7200,
+  timezone: "America/New_York",
+  metadata: {
+    title: "Team Meeting",
+    description: "Quarterly planning"
+  }
+});
+
+// Create a recurring event
+const recurringEvent = await client.events.create({
+  calendar_uid: "calendar-uid",
+  account_id: "user123",
+  start_ts: Math.floor(Date.now() / 1000) + 3600,
+  end_ts: Math.floor(Date.now() / 1000) + 7200,
+  recurrence: {
+    rule: "FREQ=WEEKLY;BYDAY=MO,WE,FR",
+    count: 10
+  },
+  metadata: {
+    title: "Daily Standup"
+  }
+});
+
+// Get an event
+const event = await client.events.get("event-uid");
+
+// Get events for multiple calendars
+const events = await client.events.getCalendarEvents({
+  calendar_uids: ["cal-1", "cal-2"],
+  start_ts: Math.floor(Date.now() / 1000),
+  end_ts: Math.floor(Date.now() / 1000) + 86400 * 7
+});
+
+// Update an event (single instance)
+const updated = await client.events.update("event-uid", {
+  account_id: "user123",
+  start_ts: newStartTime,
+  end_ts: newEndTime,
+  scope: "single"
+});
+
+// Update all instances of a recurring event
+await client.events.update("event-uid", {
+  account_id: "user123",
+  start_ts: newStartTime,
+  end_ts: newEndTime,
+  scope: "all"
+});
+
+// Toggle cancelled status
+await client.events.toggleCancelled("event-uid");
+
+// Delete an event
+await client.events.delete("event-uid", "user123", "single");
+
+// Transfer event ownership
+await client.events.transferOwnership(
+  "event-uid",
+  "new-owner-account-id",
+  "new-calendar-uid",
+  "all"
+);
+```
+
+### Reminders
+
+```typescript
+// Create a reminder (30 minutes before event)
+const reminder = await client.reminders.create("event-uid", {
+  offset_seconds: -1800,
+  account_id: "user123",
+  metadata: { method: "email" },
+  scope: "single"
+});
+
+// List reminders for an event
+const reminders = await client.reminders.list("event-uid", "user123");
+
+// Update a reminder
+const updated = await client.reminders.update("event-uid", "reminder-uid", {
+  offset_seconds: -3600,
+  metadata: { method: "push" },
+  scope: "single"
+});
+
+// Delete a reminder
+await client.reminders.delete("event-uid", "reminder-uid", "single");
+```
+
+### Webhooks
+
+```typescript
+// Create a webhook
+const webhook = await client.webhooks.create({
+  url: "https://example.com/webhook",
+  event_types: ["event.created", "event.updated", "event.deleted"],
+  retry_count: 3,
+  timeout_seconds: 30
+});
+
+// Get a webhook
+const webhook = await client.webhooks.get("webhook-uid");
+
+// List webhooks
+const webhooks = await client.webhooks.list(50, 0);
+
+// Update a webhook
+const updated = await client.webhooks.update("webhook-uid", {
+  url: "https://example.com/new-webhook",
+  is_active: true
+});
+
+// Delete a webhook
+await client.webhooks.delete("webhook-uid");
+
+// Get webhook deliveries
+const deliveries = await client.webhooks.getDeliveries("webhook-uid", 50, 0);
+```
+
+### Attendees
+
+```typescript
+// Add an attendee to an event
+const attendee = await client.attendees.create("event-uid", {
+  account_id: "user456",
+  role: "attendee",
+  metadata: { department: "engineering" },
+  scope: "single"
+});
+
+// List attendees for an event
+const attendees = await client.attendees.list("event-uid");
+
+// Get a specific attendee
+const attendee = await client.attendees.get("event-uid", "user456");
+
+// Update an attendee
+const updated = await client.attendees.update("event-uid", "user456", {
+  role: "organizer",
+  scope: "single"
+});
+
+// Update RSVP status
+await client.attendees.updateRSVP("event-uid", "user456", {
+  rsvp_status: "accepted",
+  scope: "single"
+});
+
+// Remove an attendee
+await client.attendees.delete("event-uid", "user456", "single");
+
+// Get events for an account (where they are an attendee)
+const events = await client.attendees.getAccountEvents(
+  "user456",
+  Math.floor(Date.now() / 1000),
+  Math.floor(Date.now() / 1000) + 86400 * 30,
+  "attendee",
+  "accepted"
+);
+```
+
+### Calendar Members
+
+```typescript
+// Invite members to a calendar
+await client.calendarMembers.invite("calendar-uid", {
+  members: [
+    { account_id: "user1", role: "read" },
+    { account_id: "user2", role: "write" }
+  ]
+});
+
+// List calendar members
+const members = await client.calendarMembers.list("calendar-uid");
+
+// Update a member's role
+const updated = await client.calendarMembers.update("calendar-uid", "user1", {
+  role: "write",
+  status: "confirmed"
+});
+
+// Remove a member
+await client.calendarMembers.remove("calendar-uid", "user1");
+```
+
+### ICS Import
+
+```typescript
+// Import from ICS file
+const formData = new FormData();
+formData.append("file", icsFileBlob);
+formData.append("account_id", "user123");
+formData.append("calendar_metadata", JSON.stringify({ name: "Imported Calendar" }));
+
+const result = await client.calendars.importICS(formData);
+console.log(`Imported ${result.summary.imported_events} events`);
+
+// Import from ICS URL (with automatic sync)
+const syncedCalendar = await client.calendars.importICSLink({
+  accountId: "user123",
+  icsUrl: "https://calendar.google.com/calendar/ical/example/basic.ics",
+  authType: "none", // or "basic" or "bearer"
+  syncIntervalSeconds: 86400, // 24 hours
+  calendarMetadata: { name: "External Calendar", source: "google" },
+});
+
+// Manually trigger a resync
+const resyncResult = await client.calendars.resync("calendar-uid");
+console.log(`Resynced ${resyncResult.imported_events} events`);
+```
+
+### Webhook Utilities
+
+The SDK includes utilities for verifying and handling webhook payloads:
+
+```typescript
+import {
+  WebhookUtils,
+  createWebhookVerificationMiddleware,
+  WebhookPayload,
+  isEventWebhook,
+  isCalendarWebhook,
+} from "go-scheduler-node-sdk";
+
+// Verify a webhook signature
+const rawBody = req.body; // Raw request body as string or Buffer
+const signature = req.headers["x-webhook-signature"];
+const secret = "your-webhook-secret";
+
+const verification = WebhookUtils.verifySignature(rawBody, signature, secret);
+if (verification.valid) {
+  const payload = JSON.parse(rawBody) as WebhookPayload;
+  console.log("Valid webhook:", payload.event_type);
+} else {
+  console.error("Invalid webhook:", verification.error);
+}
+
+// Parse and verify in one step
+const result = WebhookUtils.parseAndVerify(rawBody, signature, secret);
+if (result) {
+  console.log("Webhook data:", result.payload.data);
+}
+
+// Verify with timestamp freshness check
+const verification = WebhookUtils.verifyWithTimestamp(
+  rawBody,
+  signature,
+  secret,
+  300 // 5 minute tolerance
+);
+
+// Type guards for webhook payloads
+if (isEventWebhook(payload)) {
+  // TypeScript knows this is an event webhook
+  console.log("Event UID:", payload.data.event_uid);
+}
+
+if (isCalendarWebhook(payload)) {
+  // TypeScript knows this is a calendar webhook
+  console.log("Calendar UID:", payload.data.calendar_uid);
+}
+
+// Express middleware for automatic verification
+import express from "express";
+
+const app = express();
+
+app.use(express.json({
+  verify: (req, res, buf) => {
+    req.rawBody = buf.toString("utf8");
+  },
+}));
+
+app.post(
+  "/webhook",
+  createWebhookVerificationMiddleware("your-webhook-secret", {
+    rawBodyKey: "rawBody",
+    toleranceSeconds: 300,
+  }),
+  (req, res) => {
+    // Webhook is verified and parsed
+    const payload = req.webhookPayload as WebhookPayload;
+    console.log("Received:", payload.event_type);
+    res.json({ received: true });
+  }
+);
+```
+
+#### Webhook Utility Functions
+
+- **`verifySignature(payload, signature, secret)`** - Verify HMAC-SHA256 signature
+- **`computeSignature(payload, secret)`** - Compute signature for testing
+- **`parseAndVerify(rawPayload, signature, secret)`** - Parse and verify in one step
+- **`validatePayloadStructure(payload)`** - Validate webhook payload structure
+- **`isTimestampFresh(timestamp, toleranceSeconds)`** - Check timestamp freshness
+- **`verifyWithTimestamp(rawPayload, signature, secret, toleranceSeconds)`** - Verify signature and timestamp
+- **`extractSignature(headers)`** - Extract signature from headers
+- **`createWebhookVerificationMiddleware(secret, options)`** - Express middleware factory
+
+#### Webhook Type Guards
+
+- **`isCalendarWebhook(payload)`** - Check if calendar webhook
+- **`isCalendarSyncedWebhook(payload)`** - Check if calendar synced webhook
+- **`isEventWebhook(payload)`** - Check if event webhook
+- **`isReminderDueWebhook(payload)`** - Check if reminder due webhook
+- **`isAttendeeWebhook(payload)`** - Check if attendee webhook
+- **`isMemberWebhook(payload)`** - Check if member webhook
+
+## Configuration
+
+The `SchedulerClient` accepts the following configuration options:
+
+```typescript
+interface SchedulerConfig {
+  baseURL: string;           // Required: Base URL of the go-scheduler API
+  timeout?: number;          // Optional: Request timeout in milliseconds (default: 30000)
+  headers?: Record<string, string>; // Optional: Custom headers to include in all requests
+}
+```
+
+## Setting Custom Headers
+
+You can set custom headers after initializing the client:
+
+```typescript
+// Set a header
+client.setHeader("Authorization", "Bearer new-token");
+
+// Remove a header
+client.removeHeader("Authorization");
+```
+
+## Recurring Events
+
+When working with recurring events, many operations support a `scope` parameter:
+
+- `"single"`: Affects only the specific instance
+- `"all"`: Affects all instances in the series
+- `"future"`: Affects this instance and all future instances (for updates only)
+
+```typescript
+// Update only this instance
+await client.events.update("instance-uid", {
+  account_id: "user123",
+  start_ts: newTime,
+  end_ts: newTime + 3600,
+  scope: "single"
+});
+
+// Update all instances
+await client.events.update("master-uid", {
+  account_id: "user123",
+  start_ts: newTime,
+  end_ts: newTime + 3600,
+  scope: "all"
+});
+```
+
+## Error Handling
+
+The SDK throws errors with detailed information:
+
+```typescript
+try {
+  const event = await client.events.get("invalid-uid");
+} catch (error) {
+  console.error("Error:", error.message);
+  console.error("Status:", error.status);
+  console.error("Response:", error.response);
+}
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and includes full type definitions. Import types as needed:
+
+```typescript
+import {
+  Calendar,
+  Event,
+  Reminder,
+  Webhook,
+  Attendee,
+  CreateEventRequest,
+  UpdateScope
+} from "go-scheduler-node-sdk";
+```
+
+## API Reference
+
+For complete API documentation, see the [go-scheduler API documentation](https://github.com/jaysongiroux/go-scheduler).
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import { Calendars } from "./resources/calendars";
+import { Events } from "./resources/events";
+import { Reminders } from "./resources/reminders";
+import { Webhooks } from "./resources/webhooks";
+import { Attendees } from "./resources/attendees";
+import { CalendarMembers } from "./resources/calendarMembers";
+import { SchedulerConfig } from "./types";
+export declare class SchedulerClient {
+    private http;
+    calendars: Calendars;
+    events: Events;
+    reminders: Reminders;
+    webhooks: Webhooks;
+    attendees: Attendees;
+    calendarMembers: CalendarMembers;
+    constructor(config: SchedulerConfig);
+    setHeader(key: string, value: string): void;
+    removeHeader(key: string): void;
+    healthCheck(): Promise<{
+        status: string;
+    }>;
+}

package/dist/client.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchedulerClient = void 0;
+const http_1 = require("./utils/http");
+const calendars_1 = require("./resources/calendars");
+const events_1 = require("./resources/events");
+const reminders_1 = require("./resources/reminders");
+const webhooks_1 = require("./resources/webhooks");
+const attendees_1 = require("./resources/attendees");
+const calendarMembers_1 = require("./resources/calendarMembers");
+class SchedulerClient {
+    constructor(config) {
+        this.http = new http_1.HttpClient(config.baseURL, config.timeout, config.headers);
+        this.calendars = new calendars_1.Calendars(this.http);
+        this.events = new events_1.Events(this.http);
+        this.reminders = new reminders_1.Reminders(this.http);
+        this.webhooks = new webhooks_1.Webhooks(this.http);
+        this.attendees = new attendees_1.Attendees(this.http);
+        this.calendarMembers = new calendarMembers_1.CalendarMembers(this.http);
+    }
+    setHeader(key, value) {
+        this.http.setHeader(key, value);
+    }
+    removeHeader(key) {
+        this.http.removeHeader(key);
+    }
+    async healthCheck() {
+        return this.http.get("/health");
+    }
+}
+exports.SchedulerClient = SchedulerClient;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { SchedulerClient } from "./client";
+export * from "./types";
+export { Calendars } from "./resources/calendars";
+export { Events } from "./resources/events";
+export { Reminders } from "./resources/reminders";
+export { Webhooks } from "./resources/webhooks";
+export { Attendees } from "./resources/attendees";
+export { CalendarMembers } from "./resources/calendarMembers";
+export { WebhookUtils, createWebhookVerificationMiddleware, verifySignature, computeSignature, parseAndVerify, validatePayloadStructure, isTimestampFresh, verifyWithTimestamp, extractSignature, } from "./utils/webhook";

package/dist/index.js

@@ -0,0 +1,42 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractSignature = exports.verifyWithTimestamp = exports.isTimestampFresh = exports.validatePayloadStructure = exports.parseAndVerify = exports.computeSignature = exports.verifySignature = exports.createWebhookVerificationMiddleware = exports.WebhookUtils = exports.CalendarMembers = exports.Attendees = exports.Webhooks = exports.Reminders = exports.Events = exports.Calendars = exports.SchedulerClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "SchedulerClient", { enumerable: true, get: function () { return client_1.SchedulerClient; } });
+__exportStar(require("./types"), exports);
+var calendars_1 = require("./resources/calendars");
+Object.defineProperty(exports, "Calendars", { enumerable: true, get: function () { return calendars_1.Calendars; } });
+var events_1 = require("./resources/events");
+Object.defineProperty(exports, "Events", { enumerable: true, get: function () { return events_1.Events; } });
+var reminders_1 = require("./resources/reminders");
+Object.defineProperty(exports, "Reminders", { enumerable: true, get: function () { return reminders_1.Reminders; } });
+var webhooks_1 = require("./resources/webhooks");
+Object.defineProperty(exports, "Webhooks", { enumerable: true, get: function () { return webhooks_1.Webhooks; } });
+var attendees_1 = require("./resources/attendees");
+Object.defineProperty(exports, "Attendees", { enumerable: true, get: function () { return attendees_1.Attendees; } });
+var calendarMembers_1 = require("./resources/calendarMembers");
+Object.defineProperty(exports, "CalendarMembers", { enumerable: true, get: function () { return calendarMembers_1.CalendarMembers; } });
+var webhook_1 = require("./utils/webhook");
+Object.defineProperty(exports, "WebhookUtils", { enumerable: true, get: function () { return webhook_1.WebhookUtils; } });
+Object.defineProperty(exports, "createWebhookVerificationMiddleware", { enumerable: true, get: function () { return webhook_1.createWebhookVerificationMiddleware; } });
+Object.defineProperty(exports, "verifySignature", { enumerable: true, get: function () { return webhook_1.verifySignature; } });
+Object.defineProperty(exports, "computeSignature", { enumerable: true, get: function () { return webhook_1.computeSignature; } });
+Object.defineProperty(exports, "parseAndVerify", { enumerable: true, get: function () { return webhook_1.parseAndVerify; } });
+Object.defineProperty(exports, "validatePayloadStructure", { enumerable: true, get: function () { return webhook_1.validatePayloadStructure; } });
+Object.defineProperty(exports, "isTimestampFresh", { enumerable: true, get: function () { return webhook_1.isTimestampFresh; } });
+Object.defineProperty(exports, "verifyWithTimestamp", { enumerable: true, get: function () { return webhook_1.verifyWithTimestamp; } });
+Object.defineProperty(exports, "extractSignature", { enumerable: true, get: function () { return webhook_1.extractSignature; } });

package/dist/resources/attendees.d.ts

@@ -0,0 +1,31 @@
+import { HttpClient } from "../utils/http";
+import { Attendee, CreateAttendeeRequest, UpdateAttendeeRequest, UpdateAttendeeRSVPRequest } from "../types";
+export declare class Attendees {
+    private http;
+    constructor(http: HttpClient);
+    create(eventUID: string, data: CreateAttendeeRequest): Promise<{
+        attendee?: Attendee;
+        attendee_group_id?: string;
+        scope: string;
+        count: number;
+    }>;
+    list(eventUID: string, roleFilter?: string, rsvpFilter?: string): Promise<Attendee[]>;
+    get(eventUID: string, accountID: string): Promise<Attendee>;
+    update(eventUID: string, accountID: string, data: UpdateAttendeeRequest): Promise<{
+        attendee?: Attendee;
+        scope: string;
+        count: number;
+    }>;
+    delete(eventUID: string, accountID: string, scope?: "single" | "all"): Promise<{
+        message: string;
+        scope: string;
+        count: number;
+        reminders_deleted: number;
+    }>;
+    updateRSVP(eventUID: string, accountID: string, data: UpdateAttendeeRSVPRequest): Promise<{
+        attendee?: Attendee;
+        scope: string;
+        count: number;
+    }>;
+    getAccountEvents(accountID: string, startTs: number, endTs: number, roleFilter?: string, rsvpFilter?: string): Promise<any[]>;
+}

package/dist/resources/attendees.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Attendees = void 0;
+class Attendees {
+    constructor(http) {
+        this.http = http;
+    }
+    async create(eventUID, data) {
+        return this.http.post(`/api/v1/events/${eventUID}/attendees`, data);
+    }
+    async list(eventUID, roleFilter, rsvpFilter) {
+        const params = {};
+        if (roleFilter)
+            params.role = roleFilter;
+        if (rsvpFilter)
+            params.rsvp_status = rsvpFilter;
+        return this.http.get(`/api/v1/events/${eventUID}/attendees`, {
+            params: Object.keys(params).length > 0 ? params : undefined,
+        });
+    }
+    async get(eventUID, accountID) {
+        return this.http.get(`/api/v1/events/${eventUID}/attendees/${accountID}`);
+    }
+    async update(eventUID, accountID, data) {
+        return this.http.patch(`/api/v1/events/${eventUID}/attendees/${accountID}`, data);
+    }
+    async delete(eventUID, accountID, scope) {
+        const params = scope ? { scope } : undefined;
+        return this.http.delete(`/api/v1/events/${eventUID}/attendees/${accountID}`, {
+            params,
+        });
+    }
+    async updateRSVP(eventUID, accountID, data) {
+        return this.http.put(`/api/v1/events/${eventUID}/attendees/${accountID}/rsvp`, data);
+    }
+    async getAccountEvents(accountID, startTs, endTs, roleFilter, rsvpFilter) {
+        const params = {
+            account_id: accountID,
+            start_ts: startTs.toString(),
+            end_ts: endTs.toString(),
+        };
+        if (roleFilter)
+            params.role = roleFilter;
+        if (rsvpFilter)
+            params.rsvp_status = rsvpFilter;
+        return this.http.get("/api/v1/attendees/events", {
+            params,
+        });
+    }
+}
+exports.Attendees = Attendees;

package/dist/resources/calendarMembers.d.ts

@@ -0,0 +1,13 @@
+import { HttpClient } from "../utils/http";
+import { CalendarMember, InviteCalendarMembersRequest, UpdateCalendarMemberRequest } from "../types";
+export declare class CalendarMembers {
+    private http;
+    constructor(http: HttpClient);
+    invite(calendarUID: string, data: InviteCalendarMembersRequest): Promise<{
+        invited_count: number;
+        members: CalendarMember[];
+    }>;
+    list(calendarUID: string, requestingAccountID: string): Promise<CalendarMember[]>;
+    update(calendarUID: string, memberAccountID: string, requestingAccountID: string, data: UpdateCalendarMemberRequest): Promise<CalendarMember>;
+    remove(calendarUID: string, memberAccountID: string, requestingAccountID: string): Promise<void>;
+}