@kudosapi/sdk 0.1.1 → 0.1.2

package/README.md

@@ -36,6 +36,109 @@ const kudos = new Kudos({
 });
 ```
 
+## API Keys: Test vs Live
+
+KudosAPI provides two types of API keys for each project:
+
+| Key Type | Prefix | Purpose |
+|----------|--------|---------|
+| **Live** | `kudo_live_` | Production use. Events are processed and notifications are sent. |
+| **Test** | `kudo_test_` | Development/testing. Events are accepted but NOT processed or stored. |
+
+### Using Test Keys
+
+Use test keys during development to verify your integration without generating real notifications:
+
+```typescript
+// Development - events are accepted but not processed
+const kudos = new Kudos({ apiKey: 'kudo_test_xxx' });
+
+// The SDK will warn if you accidentally use a test key in production
+// "[KudosAPI] Warning: Using a test API key in production. Events will not be processed."
+```
+
+### Environment-Based Configuration
+
+A common pattern is to use environment variables to switch between test and live keys:
+
+```typescript
+const kudos = new Kudos({
+  apiKey: process.env.KUDOS_API_KEY!, // kudo_test_xxx in dev, kudo_live_xxx in prod
+});
+```
+
+```bash
+# .env.local (development)
+KUDOS_API_KEY=kudo_test_xxx
+
+# .env.production
+KUDOS_API_KEY=kudo_live_xxx
+```
+
+## Local Development
+
+### Testing Against Local KudosAPI
+
+If you're running KudosAPI locally, override the `baseUrl`:
+
+```typescript
+const kudos = new Kudos({
+  apiKey: 'kudo_test_xxx',
+  baseUrl: 'http://localhost:3000', // Your local KudosAPI instance
+  debug: true, // Enable debug logging to see requests
+});
+```
+
+### Mocking in Tests
+
+For unit tests, mock the SDK to avoid network calls:
+
+```typescript
+// __mocks__/@kudosapi/sdk.ts (Jest/Vitest)
+export class Kudos {
+  track = vi.fn().mockResolvedValue({ success: true, eventId: 'evt_mock' });
+  sale = vi.fn().mockResolvedValue({ success: true, eventId: 'evt_mock' });
+  signup = vi.fn().mockResolvedValue({ success: true, eventId: 'evt_mock' });
+  milestone = vi.fn().mockResolvedValue({ success: true, eventId: 'evt_mock' });
+}
+```
+
+```typescript
+// your-code.test.ts
+vi.mock('@kudosapi/sdk');
+
+it('tracks sale on checkout', async () => {
+  const kudos = new Kudos({ apiKey: 'test' });
+  await processCheckout(kudos);
+  expect(kudos.sale).toHaveBeenCalledWith(99, 'USD', expect.any(Object));
+});
+```
+
+### Integration Testing
+
+For integration tests that need to hit the real API, use test keys:
+
+```typescript
+// integration.test.ts
+import { Kudos } from '@kudosapi/sdk';
+
+const kudos = new Kudos({
+  apiKey: process.env.KUDOS_TEST_API_KEY!, // kudo_test_xxx
+  debug: true,
+});
+
+it('successfully sends event to KudosAPI', async () => {
+  const result = await kudos.track({
+    type: 'integration_test',
+    title: 'Test event',
+  });
+
+  // Test keys return success but don't process events
+  expect(result.success).toBe(true);
+  expect(result.eventId).toMatch(/^evt_/);
+});
+```
+
 ## Methods
 
 ### `track(event, options?)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudosapi/sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Official SDK for KudosAPI - Get positive notifications when good things happen in your app",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",