swcombine-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,404 @@
+# SW Combine SDK for Node.js
+
+<div align="center">
+
+**Comprehensive TypeScript SDK for the Star Wars Combine API v2.0**
+
+[![npm version](https://img.shields.io/npm/v/swcombine-sdk.svg)](https://www.npmjs.com/package/swcombine-sdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[Features](#features) •
+[Installation](#installation) •
+[Quick Start](#quick-start) •
+[Documentation](#documentation) •
+[Examples](#examples)
+
+</div>
+
+## Features
+
+- ✨ **Full API Coverage** - All 60+ endpoints across 11 resource categories
+- 🔐 **OAuth 2.0 Built-in** - Complete OAuth flow with automatic token refresh
+- 📘 **TypeScript First** - Full type definitions with IntelliSense support
+- 🎯 **Type-Safe Scopes** - 230+ OAuth scope constants with autocomplete
+- 🔄 **Automatic Retries** - Exponential backoff for failed requests
+- 🌐 **Modern & Universal** - ES Modules + CommonJS, Node.js 18+
+- 🛠️ **Developer Tools** - Helper scripts for OAuth and testing
+- 📦 **Zero Dependencies** (except axios)
+
+## Installation
+
+```bash
+npm install swcombine-sdk
+# or
+yarn add swcombine-sdk
+# or
+pnpm add swcombine-sdk
+```
+
+## Quick Start
+
+### 1. Initialize the Client
+
+```typescript
+import { SWCombine } from 'swcombine-sdk';
+
+const client = new SWCombine({
+  clientId: process.env.SWC_CLIENT_ID!,
+  clientSecret: process.env.SWC_CLIENT_SECRET!,
+  accessToken: process.env.SWC_ACCESS_TOKEN, // Optional
+});
+```
+
+### 2. Make API Calls
+
+```typescript
+// Get public character information (no auth required)
+const character = await client.character.getByHandle({
+  handle: 'character-handle',
+});
+
+console.log(character.uid);    // "1:12345"
+console.log(character.name);   // "Character Name"
+```
+
+### 3. Authenticated Endpoints
+
+```typescript
+// For authenticated endpoints, provide an access token
+const authenticatedClient = new SWCombine({
+  clientId: process.env.SWC_CLIENT_ID!,
+  clientSecret: process.env.SWC_CLIENT_SECRET!,
+  accessToken: process.env.SWC_ACCESS_TOKEN!,
+});
+
+// Get character details
+const character = await authenticatedClient.character.get({
+  uid: '1:12345',
+});
+
+// Get character messages
+const messages = await authenticatedClient.character.messages.list({
+  uid: '1:12345',
+  mode: 'received',
+});
+
+// Get faction information
+const faction = await authenticatedClient.faction.get({
+  uid: '20:123',
+});
+```
+
+## OAuth Authentication
+
+### Quick OAuth Setup
+
+Use the included helper script to get an access token:
+
+```bash
+# 1. Add your credentials to .env
+echo "SWC_CLIENT_ID=your_client_id" >> .env
+echo "SWC_CLIENT_SECRET=your_client_secret" >> .env
+
+# 2. Run the OAuth helper
+npm run get-token
+
+# 3. Visit http://localhost:3000 in your browser
+# 4. Authorize the app and copy the token to .env
+```
+
+### Manual OAuth Flow
+
+```typescript
+import { SWCombine, CharacterScopes, MessageScopes } from 'swcombine-sdk';
+
+const client = new SWCombine({
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+  redirectUri: 'http://localhost:3000/callback',
+  accessType: 'offline', // Get refresh token
+});
+
+// 1. Generate authorization URL
+const authUrl = client.auth.getAuthorizationUrl({
+  scopes: [
+    CharacterScopes.READ,
+    CharacterScopes.STATS,
+    MessageScopes.READ,
+    MessageScopes.SEND,
+  ],
+  state: 'random-csrf-token',
+});
+
+// 2. Redirect user to authUrl...
+
+// 3. Handle callback
+const result = await client.auth.handleCallback(req.query);
+
+if (result.success) {
+  const token = result.token!;
+  console.log('Access Token:', token.accessToken);
+  console.log('Refresh Token:', token.refreshToken);
+}
+```
+
+## Type-Safe OAuth Scopes
+
+```typescript
+import {
+  CharacterScopes,
+  MessageScopes,
+  Scopes,
+  getAllScopes,
+  getReadOnlyScopes,
+} from 'swcombine-sdk';
+
+// Use constants with autocomplete
+const scopes = [
+  CharacterScopes.READ,      // ✓ TypeScript suggests all scopes
+  CharacterScopes.STATS,
+  MessageScopes.SEND,
+  Scopes.PersonalInventory.SHIPS.READ,
+];
+
+// Or use helpers
+const readOnly = getReadOnlyScopes();
+const everything = getAllScopes();
+```
+
+See [OAuth Scopes Guide](docs/SCOPES.md) for all 230+ available scopes.
+
+## API Resources
+
+The SDK provides access to all SW Combine API resources:
+
+### Characters
+
+```typescript
+// Public endpoints
+await client.character.getByHandle({ handle: 'character-handle' });
+
+// Authenticated endpoints
+await client.character.get({ uid: '1:12345' });
+await client.character.skills.list({ uid: '1:12345' });
+await client.character.privileges.list({ uid: '1:12345' });
+await client.character.credits.get({ uid: '1:12345' });
+await client.character.messages.list({ uid: '1:12345', mode: 'received' });
+await client.character.permissions.list({ uid: '1:12345' });
+```
+
+### Factions
+
+```typescript
+await client.faction.list();
+await client.faction.get({ uid: '20:123' });
+await client.faction.members.list({ uid: '20:123' });
+await client.faction.budgets.list({ uid: '20:123' });
+```
+
+### Inventory
+
+```typescript
+await client.inventory.get({ uid: '1:12345' });
+await client.inventory.entities.list({
+  uid: '1:12345',
+  entityType: 'vehicle',
+  assignType: 'pilot',
+});
+```
+
+### Galaxy
+
+```typescript
+await client.galaxy.systems.list();
+await client.galaxy.planets.list();
+await client.galaxy.sectors.list();
+```
+
+### Events, Location, Datacards, and More
+
+```typescript
+await client.events.list({ eventMode: 'character', eventType: 'all' });
+await client.location.get({ entityType: 'character', uid: '1:12345' });
+await client.datacard.list({ factionId: '20:123' });
+await client.market.listings.list();
+await client.news.list();
+await client.types.races.list();
+```
+
+See [API Documentation](docs/API.md) for complete reference.
+
+## Error Handling
+
+```typescript
+import { SWCError } from 'swcombine-sdk';
+
+try {
+  const character = await client.character.get({ uid: '1:12345' });
+} catch (error) {
+  if (error instanceof SWCError) {
+    console.error('Status:', error.statusCode);     // 404
+    console.error('Message:', error.message);       // "Resource not found"
+    console.error('Type:', error.type);             // "not_found"
+    console.error('Retryable:', error.retryable);   // false
+  }
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with intelligent type inference:
+
+```typescript
+// Types are automatically inferred
+const character = await client.character.get({ uid: '1:12345' });
+// character: Character
+
+// Request parameters are typed
+await client.character.messages.list({
+  uid: '1:12345',
+  mode: 'received', // TypeScript knows valid values
+  // mode: 'invalid', // ❌ TypeScript error
+});
+```
+
+## Configuration Options
+
+```typescript
+interface ClientConfig {
+  // Required OAuth credentials
+  clientId: string;
+  clientSecret: string;
+
+  // Optional authentication
+  accessToken?: string;
+  refreshToken?: string;
+
+  // Optional OAuth settings
+  redirectUri?: string;
+  accessType?: 'online' | 'offline';
+
+  // Optional HTTP settings
+  baseURL?: string;           // Default: https://www.swcombine.com/ws/v2.0/
+  timeout?: number;           // Default: 30000 (30 seconds)
+  maxRetries?: number;        // Default: 3
+  retryDelay?: number;        // Default: 1000ms
+  debug?: boolean;            // Default: false
+}
+```
+
+## Examples
+
+See the [examples](examples/) directory for complete working examples:
+
+- **[OAuth Scopes](examples/oauth-scopes-example.ts)** - 10 examples of scope usage
+
+### Basic Usage
+
+```typescript
+import { SWCombine } from 'swcombine-sdk';
+
+const client = new SWCombine({
+  clientId: process.env.SWC_CLIENT_ID!,
+  clientSecret: process.env.SWC_CLIENT_SECRET!,
+});
+
+// Get character info
+const character = await client.character.getByHandle({
+  handle: 'character-name',
+});
+
+console.log(`${character.name} (${character.uid})`);
+```
+
+## Developer Tools
+
+### Get OAuth Token
+
+Interactive OAuth flow to obtain access tokens:
+
+```bash
+npm run get-token
+```
+
+### Get Character UID
+
+Quickly get a character's UID from their handle:
+
+```bash
+npm run get-character-uid YourHandle
+```
+
+### Run Integration Tests
+
+```bash
+npm run test:integration
+```
+
+## Documentation
+
+- **[Getting Started Guide](docs/GETTING_STARTED.md)** - Detailed setup and usage
+- **[Authentication Guide](docs/AUTHENTICATION.md)** - OAuth 2.0 setup and token management
+- **[OAuth Scopes Reference](docs/SCOPES.md)** - Complete scope documentation
+- **[API Reference](docs/API.md)** - Detailed API endpoint documentation
+- **[Examples](examples/)** - Working code examples
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Run integration tests
+npm run test:integration
+
+# Lint
+npm run lint
+
+# Format code
+npm run format
+```
+
+## Requirements
+
+- Node.js 18 or higher
+- TypeScript 5.0 or higher (for TypeScript projects)
+
+## Links
+
+- [SW Combine API Documentation](https://www.swcombine.com/ws/developers/)
+- [npm Package](https://www.npmjs.com/package/swcombine-sdk)
+- [GitHub Repository](https://github.com/yourusername/swcombine-sdk-nodejs)
+
+## License
+
+MIT © [Your Name]
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## Support
+
+- 📖 Check the [documentation](docs/)
+- 💬 Submit issues on [GitHub](https://github.com/yourusername/swcombine-sdk-nodejs/issues)
+- 📧 Contact support
+
+---
+
+<div align="center">
+Made with ❤️ for the Star Wars Combine community
+</div>

package/dist/cjs/SWCombine.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Main SW Combine SDK client
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SWCombine = void 0;
+const HttpClient_js_1 = require("./http/HttpClient.js");
+const OAuthClient_js_1 = require("./auth/OAuthClient.js");
+const TokenManager_js_1 = require("./auth/TokenManager.js");
+// Import all resource classes
+const ApiResource_js_1 = require("./resources/ApiResource.js");
+const CharacterResource_js_1 = require("./resources/CharacterResource.js");
+const FactionResource_js_1 = require("./resources/FactionResource.js");
+const GalaxyResource_js_1 = require("./resources/GalaxyResource.js");
+const InventoryResource_js_1 = require("./resources/InventoryResource.js");
+const MarketResource_js_1 = require("./resources/MarketResource.js");
+const NewsResource_js_1 = require("./resources/NewsResource.js");
+const TypesResource_js_1 = require("./resources/TypesResource.js");
+const EventsResource_js_1 = require("./resources/EventsResource.js");
+const LocationResource_js_1 = require("./resources/LocationResource.js");
+const DatacardResource_js_1 = require("./resources/DatacardResource.js");
+/**
+ * Main SW Combine SDK client
+ */
+class SWCombine {
+    constructor(config) {
+        this.config = config;
+        // Initialize token manager
+        this.tokenManager = new TokenManager_js_1.TokenManager(config.token);
+        // Initialize OAuth client
+        this.oauthClient = new OAuthClient_js_1.OAuthClient({
+            clientId: config.clientId,
+            clientSecret: config.clientSecret,
+            redirectUri: config.redirectUri,
+            accessType: config.accessType,
+        });
+        // Set up token refresh callback
+        this.tokenManager.setRefreshCallback(async () => {
+            const refreshToken = this.tokenManager.getRefreshToken();
+            if (!refreshToken) {
+                throw new Error('No refresh token available');
+            }
+            return this.oauthClient.refreshToken(refreshToken);
+        });
+        // Initialize HTTP client
+        this.http = new HttpClient_js_1.HttpClient({
+            baseURL: config.baseURL,
+            timeout: config.timeout,
+            maxRetries: config.maxRetries,
+            retryDelay: config.retryDelay,
+            debug: config.debug,
+        }, this.tokenManager);
+        // Initialize all resources
+        this.api = new ApiResource_js_1.ApiResource(this.http);
+        this.character = new CharacterResource_js_1.CharacterResource(this.http);
+        this.faction = new FactionResource_js_1.FactionResource(this.http);
+        this.galaxy = new GalaxyResource_js_1.GalaxyResource(this.http);
+        this.inventory = new InventoryResource_js_1.InventoryResource(this.http);
+        this.market = new MarketResource_js_1.MarketResource(this.http);
+        this.news = new NewsResource_js_1.NewsResource(this.http);
+        this.types = new TypesResource_js_1.TypesResource(this.http);
+        this.events = new EventsResource_js_1.EventsResource(this.http);
+        this.location = new LocationResource_js_1.LocationResource(this.http);
+        this.datacard = new DatacardResource_js_1.DatacardResource(this.http);
+        // Set up auth operations
+        this.auth = {
+            getAuthorizationUrl: (options) => {
+                return this.oauthClient.getAuthorizationUrl(options);
+            },
+            handleCallback: async (query) => {
+                const result = await this.oauthClient.handleCallback(query);
+                if (result.success && result.token) {
+                    this.tokenManager.setToken(result.token);
+                }
+                return result;
+            },
+            revokeToken: async (refreshToken) => {
+                return this.oauthClient.revokeToken(refreshToken);
+            },
+        };
+    }
+    /**
+     * Set the access token
+     */
+    setToken(token) {
+        this.tokenManager.setToken(token);
+    }
+    /**
+     * Get the current token
+     */
+    getToken() {
+        return this.tokenManager.getToken();
+    }
+    /**
+     * Clear the token
+     */
+    clearToken() {
+        this.tokenManager.clear();
+    }
+    /**
+     * Manually refresh the token
+     */
+    async refreshToken() {
+        await this.tokenManager.refreshToken();
+    }
+    /**
+     * Check if token is expired
+     */
+    isTokenExpired() {
+        return this.tokenManager.isExpired();
+    }
+    /**
+     * Check if refresh token is available
+     */
+    hasRefreshToken() {
+        return this.tokenManager.hasRefreshToken();
+    }
+}
+exports.SWCombine = SWCombine;
+//# sourceMappingURL=SWCombine.js.map

package/dist/cjs/SWCombine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SWCombine.js","sourceRoot":"","sources":["../../src/SWCombine.ts"],"names":[],"mappings":"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"}