@noematicsllc/talk-sdk 0.0.1

package/README.md

@@ -0,0 +1,171 @@
+# @noematicsllc/talk-sdk
+
+TypeScript SDK for the Nextcloud Talk API.
+
+## Installation
+
+```bash
+npm install @noematicsllc/talk-sdk
+# or
+pnpm add @noematicsllc/talk-sdk
+```
+
+## Quick Start
+
+```typescript
+import { TalkClient } from '@noematicsllc/talk-sdk';
+
+const client = new TalkClient({
+  host: 'https://nextcloud.local',
+  username: 'admin',
+  password: 'app-password'
+});
+
+// List all rooms
+const rooms = await client.rooms.list();
+
+// Find a room by token
+const targetRoom = rooms.find(r => r.token === 'abcdefgh');
+
+// Send a message
+await targetRoom.sendMessage("Automated system check initialized.");
+```
+
+## Architecture
+
+The SDK uses a 4-layer architecture:
+
+### 1. Transport Layer (`HttpClient`)
+
+Base HTTP client using the native Fetch API. Automatically injects mandatory OCS headers:
+- `OCS-APIRequest: true`
+- `Accept: application/json`
+- `Authorization: Basic ...`
+
+### 2. Resource Layer
+
+Logical modules mapped to specific API versions:
+
+| Resource | API Version | Base Path |
+|----------|-------------|-----------|
+| `RoomResource` | v4 | `/api/v4/room` |
+| `ParticipantResource` | v4 | `/api/v4/room/{token}/participants` |
+| `CallResource` | v4 | `/api/v4/call` |
+| `ChatResource` | v1 | `/api/v1/chat` |
+| `PollResource` | v1 | `/api/v1/poll` |
+| `ReactionResource` | v1 | `/api/v1/reaction` |
+
+### 3. Normalization Layer
+
+DTO mappers that strip the `ocs.meta` and `ocs.data` envelopes, returning clean, flat objects.
+
+### 4. Domain Layer
+
+High-level entities like `Room` that encapsulate both the `token` (string) and `id` (integer) to handle the API's identifier inconsistencies.
+
+## Room Entity
+
+The `Room` class provides a high-level interface for room operations:
+
+```typescript
+const room = await client.rooms.get('abcdefgh');
+
+// Chat
+await room.sendMessage("Hello!");
+const messages = await room.getHistory({ limit: 50 });
+const result = await room.pollMessages({ lastKnownMessageId: 123 });
+
+// Participants
+const participants = await room.getParticipants();
+await room.addParticipant('user-id');
+
+// Calls
+await room.joinCall({ flags: 7 });
+const peers = await room.getCallPeers();
+await room.leaveCall();
+
+// Polls
+await room.createPoll({
+  question: "What's for lunch?",
+  options: ["Pizza", "Sushi", "Tacos"]
+});
+
+// Reactions
+await room.addReaction(messageId, "👍");
+```
+
+## Message Polling
+
+Implement efficient message polling using the spec's pattern:
+
+```typescript
+let lastKnownMessageId = 0;
+
+while (polling) {
+  const result = await room.pollMessages({
+    lastKnownMessageId,
+    timeout: 30, // Long-poll timeout
+  });
+
+  for (const message of result.messages) {
+    console.log(`${message.actorDisplayName}: ${message.message}`);
+  }
+
+  if (result.lastKnownMessageId) {
+    lastKnownMessageId = result.lastKnownMessageId;
+  }
+}
+```
+
+## Direct Resource Access
+
+For advanced use cases, access resources directly:
+
+```typescript
+// Direct resource access
+const roomData = await client.roomResource.get('token');
+const messages = await client.chat.receiveMessages('token', {
+  lookIntoFuture: 0,
+  limit: 100,
+});
+
+// Raw HTTP access
+const response = await client.http.get('/custom/endpoint');
+```
+
+## Types
+
+All API types are exported for TypeScript users:
+
+```typescript
+import {
+  TalkRoom,
+  TalkChatMessage,
+  TalkParticipant,
+  ConversationType,
+  ParticipantType,
+  Permission,
+  InCallFlag,
+} from '@noematicsllc/talk-sdk';
+```
+
+## Error Handling
+
+The SDK throws `HttpClientError` for API errors:
+
+```typescript
+import { HttpClientError } from '@noematicsllc/talk-sdk';
+
+try {
+  await client.rooms.get('invalid-token');
+} catch (error) {
+  if (error instanceof HttpClientError) {
+    console.error(`HTTP ${error.status}: ${error.message}`);
+    console.error(`OCS Status: ${error.ocsStatus}`);
+  }
+}
+```
+
+## License
+
+MIT