@optimizely-opal/opal-tools-sdk 0.1.0-dev → 0.1.2-dev

package/README.md

@@ -4,11 +4,11 @@ This SDK simplifies the creation of tools services compatible with the Opal Tool
 
 ## Features
 
-- Type definitions for tools and parameters
-- Express middleware for discovery endpoints
-- Decorators for tool registration
-- Parameter validation
+- Easy definition of tool functions with decorators
+- Automatic generation of discovery endpoints
+- Parameter validation and type checking
 - Authentication helpers
+- Express integration
 
 ## Installation
 
@@ -22,14 +22,14 @@ npm install @optimizely-opal/opal-tools-sdk
 import { ToolsService, tool } from '@optimizely-opal/opal-tools-sdk';
 import express from 'express';
 
+const app = express();
+const toolsService = new ToolsService(app);
+
 interface WeatherParameters {
   location: string;
-  units?: string;
+  units: string;
 }
 
-const app = express();
-const toolsService = new ToolsService(app);
-
 @tool({
   name: 'get_weather',
   description: 'Gets current weather for a location'
@@ -40,7 +40,85 @@ async function getWeather(parameters: WeatherParameters) {
 }
 
 // Discovery endpoint is automatically created at /discovery
-app.listen(3000);
+```
+
+## Authentication
+
+The SDK provides two ways to require authentication for your tools:
+
+### 1. Using the `@requiresAuth` decorator
+
+```typescript
+import { ToolsService, tool } from '@optimizely-opal/opal-tools-sdk';
+import { requiresAuth } from '@optimizely-opal/opal-tools-sdk/auth';
+import express from 'express';
+
+const app = express();
+const toolsService = new ToolsService(app);
+
+interface CalendarParameters {
+  date: string;
+  timezone?: string;
+}
+
+// Single authentication requirement
+@requiresAuth({ provider: 'google', scopeBundle: 'calendar', required: true })
+@tool({
+  name: 'get_calendar_events',
+  description: 'Gets calendar events for a date'
+})
+async function getCalendarEvents(parameters: CalendarParameters, authData?: any) {
+  // The authData parameter contains authentication information
+  const token = authData?.credentials?.token || '';
+  
+  // Use the token to make authenticated requests
+  // ...
+  
+  return { events: ['Meeting at 10:00', 'Lunch at 12:00'] };
+}
+
+// Multiple authentication requirements (tool can work with either provider)
+@requiresAuth({ provider: 'google', scopeBundle: 'calendar', required: true })
+@requiresAuth({ provider: 'microsoft', scopeBundle: 'outlook', required: true })
+@tool({
+  name: 'get_calendar_availability',
+  description: 'Check calendar availability'
+})
+async function getCalendarAvailability(parameters: CalendarParameters, authData?: any) {
+  const provider = authData?.provider || '';
+  const token = authData?.credentials?.token || '';
+  
+  if (provider === 'google') {
+    // Use Google Calendar API
+  } else if (provider === 'microsoft') {
+    // Use Microsoft Outlook API
+  }
+  
+  return { available: true, provider_used: provider };
+}
+```
+
+### 2. Specifying auth requirements in the `@tool` decorator
+
+```typescript
+interface EmailParameters {
+  limit?: number;
+  folder?: string;
+}
+
+@tool({
+  name: 'get_email',
+  description: 'Gets emails from the user\'s inbox',
+  authRequirements: {
+    provider: 'google',
+    scopeBundle: 'gmail',
+    required: true
+  }
+})
+async function getEmail(parameters: EmailParameters, authData?: any) {
+  // Implementation...
+  return { emails: ['Email 1', 'Email 2'] };
+}
 ```
 
 ## Documentation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optimizely-opal/opal-tools-sdk",
-  "version": "0.1.0-dev",
+  "version": "0.1.2-dev",
   "description": "SDK for creating Opal-compatible tools services",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",