Add public API with TypeScript SDK for third-party integrations #133

2025-10-30T16:55:56-05:00

Copilot commented

2025-10-30 16:55:56 -05:00

(Migrated from github.com)

Implements RESTful public API and TypeScript/JavaScript SDK for third-party integrations with analytics, timeline, and user management capabilities.

SDK Package (`@spywatcher/sdk`)

Type-safe client with full TypeScript definitions for all endpoints
Error handling: Custom error classes (AuthenticationError, RateLimitError, ValidationError)
Build outputs: CommonJS (8.64 KB), ESM (6.77 KB), type definitions
Zero vulnerabilities: axios upgraded to 1.12.0

import { Spywatcher } from '@spywatcher/sdk';

const client = new Spywatcher({
  baseUrl: 'https://api.spywatcher.com/api',
  apiKey: process.env.SPYWATCHER_API_KEY
});

// Type-safe analytics queries
const ghosts = await client.analytics.getGhosts({ 
  startDate: '2024-01-01',
  page: 1 
});

// Automatic error handling
try {
  await client.getSuspicionData();
} catch (error) {
  if (error instanceof RateLimitError) {
    // Handle rate limit
  }
}

Public API Routes

/api/public/docs: JSON documentation with all endpoints, parameters, types, and examples
/api/public/openapi: OpenAPI 3.0 specification for tooling integration
/api/public/test: API key validation endpoint

API Coverage

All major endpoints covered:

Analytics: ghosts, lurkers, heatmap, roles, clients, shifts
Suspicion: behavioral pattern detection
Timeline: event tracking
Bans: guild/user management
Auth: API key CRUD operations

Rate Limiting

Added publicApiLimiter: 60 requests/minute for public API endpoints, reusing existing Redis-backed rate limiting infrastructure.

Documentation

PUBLIC_API.md: Complete endpoint reference with cURL, JavaScript, Python examples
DEVELOPER_GUIDE.md: Onboarding guide with common use cases and best practices
SDK README: Installation, usage, error handling patterns
SDK_IMPLEMENTATION.md: Architecture and technical details

Test Coverage

SDK: 4 unit tests validating client initialization and error handling
Integration: 7 tests covering public API routes and documentation endpoints

Implementation Notes

Extends existing API key authentication (spy_live_... format) and rate limiting middleware without modifying core infrastructure. Query parameter types use index signatures for type safety while maintaining flexibility.

Original prompt

This section details on the original issue you should resolve

<issue_title>Public API & SDK - Third-Party Integration Support</issue_title>
<issue_description>## 🎯 Objective Design public API with JavaScript/TypeScript SDK for third-party integrations. ## 📋 Requirements - RESTful API endpoints - API key authentication with OAuth2 - JavaScript/TypeScript SDK with types - Complete API documentation - Code examples and guides ## 🎯 Success Criteria - API fully documented - SDK published to npm - Rate limiting enforced - Example applications created ## ⏱️ Estimated Effort 7-10 days</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes Public API & SDK - Third-Party Integration Support (subculture-collective/discord-spywatcher#36)

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Implements RESTful public API and TypeScript/JavaScript SDK for third-party integrations with analytics, timeline, and user management capabilities. ## SDK Package (`@spywatcher/sdk`) - **Type-safe client** with full TypeScript definitions for all endpoints - **Error handling**: Custom error classes (`AuthenticationError`, `RateLimitError`, `ValidationError`) - **Build outputs**: CommonJS (8.64 KB), ESM (6.77 KB), type definitions - **Zero vulnerabilities**: axios upgraded to 1.12.0 ```typescript import { Spywatcher } from '@spywatcher/sdk'; const client = new Spywatcher({ baseUrl: 'https://api.spywatcher.com/api', apiKey: process.env.SPYWATCHER_API_KEY }); // Type-safe analytics queries const ghosts = await client.analytics.getGhosts({ startDate: '2024-01-01', page: 1 }); // Automatic error handling try { await client.getSuspicionData(); } catch (error) { if (error instanceof RateLimitError) { // Handle rate limit } } ``` ## Public API Routes - **`/api/public/docs`**: JSON documentation with all endpoints, parameters, types, and examples - **`/api/public/openapi`**: OpenAPI 3.0 specification for tooling integration - **`/api/public/test`**: API key validation endpoint ## API Coverage All major endpoints covered: - Analytics: ghosts, lurkers, heatmap, roles, clients, shifts - Suspicion: behavioral pattern detection - Timeline: event tracking - Bans: guild/user management - Auth: API key CRUD operations ## Rate Limiting Added `publicApiLimiter`: 60 requests/minute for public API endpoints, reusing existing Redis-backed rate limiting infrastructure. ## Documentation - **PUBLIC_API.md**: Complete endpoint reference with cURL, JavaScript, Python examples - **DEVELOPER_GUIDE.md**: Onboarding guide with common use cases and best practices - **SDK README**: Installation, usage, error handling patterns - **SDK_IMPLEMENTATION.md**: Architecture and technical details ## Test Coverage - SDK: 4 unit tests validating client initialization and error handling - Integration: 7 tests covering public API routes and documentation endpoints ## Implementation Notes Extends existing API key authentication (`spy_live_...` format) and rate limiting middleware without modifying core infrastructure. Query parameter types use index signatures for type safety while maintaining flexibility.  <details> <summary>Original prompt</summary> > > ---- > > *This section details on the original issue you should resolve* > > <issue_title>Public API & SDK - Third-Party Integration Support</issue_title> > <issue_description>## 🎯 Objective Design public API with JavaScript/TypeScript SDK for third-party integrations. ## 📋 Requirements - RESTful API endpoints - API key authentication with OAuth2 - JavaScript/TypeScript SDK with types - Complete API documentation - Code examples and guides ## 🎯 Success Criteria - API fully documented - SDK published to npm - Rate limiting enforced - Example applications created ## ⏱️ Estimated Effort 7-10 days</issue_description> > > ## Comments on the Issue (you are @copilot in this section) > > <comments> > </comments> > </details> - Fixes subculture-collective/discord-spywatcher#36  --- 💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://gh.io/copilot-coding-agent-survey).

PatrickFanella (Migrated from github.com) reviewed 2025-10-30 16:55:56 -05:00

onnwee (Migrated from github.com) reviewed 2025-10-30 16:55:56 -05:00

copilot-pull-request-reviewer[bot] (Migrated from github.com) reviewed 2025-10-30 17:36:34 -05:00

copilot-pull-request-reviewer[bot] (Migrated from github.com) left a comment

Pull Request Overview

This PR implements a comprehensive Public API and TypeScript/JavaScript SDK for the Discord Spywatcher platform. The changes introduce a complete third-party integration solution with a publishable npm package, extensive documentation, example applications, and backend API documentation endpoints.

Key Changes

Created a full-featured TypeScript SDK package (@spywatcher/sdk) with promise-based API, comprehensive type definitions, and automatic error handling
Added public API documentation endpoints (/api/public/docs, /api/public/openapi) with JSON and OpenAPI 3.0 specifications
Implemented extensive documentation including PUBLIC_API.md, DEVELOPER_GUIDE.md, and SDK README.md with usage examples and best practices

Reviewed Changes

Copilot reviewed 23 out of 24 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
sdk/package.json	SDK package configuration with dependencies and build scripts
sdk/src/types.ts	Complete TypeScript type definitions for all API data structures
sdk/src/client.ts	Base HTTP client with axios, error handling, and authentication
sdk/src/analytics.ts	Analytics API module with methods for ghosts, lurkers, heatmaps, etc.
sdk/src/spywatcher.ts	Main SDK class extending analytics with timeline, suspicion, and ban APIs
sdk/src/index.ts	Package entry point exporting all SDK components
sdk/tsconfig.json	TypeScript configuration for the SDK
sdk/jest.config.js	Jest test configuration
sdk/src/tests/client.test.ts	Unit tests for the client initialization and validation
backend/src/routes/publicApi.ts	Public API documentation and test endpoints
backend/src/routes/api.ts	Integration of public API routes
backend/src/middleware/rateLimiter.ts	Rate limiter for public API endpoints
backend/tests/integration/routes/publicApi.test.ts	Integration tests for public API routes
docs/PUBLIC_API.md	Complete public API reference documentation
docs/DEVELOPER_GUIDE.md	Developer guide with examples and best practices
sdk/README.md	SDK usage documentation
sdk/examples/*.ts	Example applications demonstrating SDK usage
SDK_IMPLEMENTATION.md	Implementation summary document
README.md	Updated main README with API/SDK information

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

## Pull Request Overview This PR implements a comprehensive Public API and TypeScript/JavaScript SDK for the Discord Spywatcher platform. The changes introduce a complete third-party integration solution with a publishable npm package, extensive documentation, example applications, and backend API documentation endpoints. ### Key Changes - Created a full-featured TypeScript SDK package (`@spywatcher/sdk`) with promise-based API, comprehensive type definitions, and automatic error handling - Added public API documentation endpoints (`/api/public/docs`, `/api/public/openapi`) with JSON and OpenAPI 3.0 specifications - Implemented extensive documentation including PUBLIC_API.md, DEVELOPER_GUIDE.md, and SDK README.md with usage examples and best practices ### Reviewed Changes Copilot reviewed 23 out of 24 changed files in this pull request and generated no comments. <details> <summary>Show a summary per file</summary> | File | Description | | ---- | ----------- | | sdk/package.json | SDK package configuration with dependencies and build scripts | | sdk/src/types.ts | Complete TypeScript type definitions for all API data structures | | sdk/src/client.ts | Base HTTP client with axios, error handling, and authentication | | sdk/src/analytics.ts | Analytics API module with methods for ghosts, lurkers, heatmaps, etc. | | sdk/src/spywatcher.ts | Main SDK class extending analytics with timeline, suspicion, and ban APIs | | sdk/src/index.ts | Package entry point exporting all SDK components | | sdk/tsconfig.json | TypeScript configuration for the SDK | | sdk/jest.config.js | Jest test configuration | | sdk/src/__tests__/client.test.ts | Unit tests for the client initialization and validation | | backend/src/routes/publicApi.ts | Public API documentation and test endpoints | | backend/src/routes/api.ts | Integration of public API routes | | backend/src/middleware/rateLimiter.ts | Rate limiter for public API endpoints | | backend/__tests__/integration/routes/publicApi.test.ts | Integration tests for public API routes | | docs/PUBLIC_API.md | Complete public API reference documentation | | docs/DEVELOPER_GUIDE.md | Developer guide with examples and best practices | | sdk/README.md | SDK usage documentation | | sdk/examples/*.ts | Example applications demonstrating SDK usage | | SDK_IMPLEMENTATION.md | Implementation summary document | | README.md | Updated main README with API/SDK information | </details> --- 💡 <a href="/subculture-collective/discord-spywatcher/new/main/.github?filename=*.instructions.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add Copilot custom instructions</a> for smarter, more guided reviews. <a href="https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn how to get started</a>.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: subculture-collective/discord-spywatcher#133