@omniq/sdk 0.1.0

package/README.md

@@ -0,0 +1,360 @@
+# @omniq/sdk
+
+Typed SDK for the [OMNIQ](https://omniq.pro) Platform API. Zero dependencies — uses native `fetch`.
+
+## Quick Start
+
+```bash
+npm install @omniq/sdk
+# or
+pnpm add @omniq/sdk
+```
+
+```typescript
+import { OmniqClient } from '@omniq/sdk';
+
+const client = new OmniqClient({
+  baseUrl: 'https://app.omniq.pro/api/v1',
+  token: 'pat_abc123…',
+});
+
+const projects = await client.projects.list();
+console.log(projects);
+```
+
+## Authentication
+
+### Personal Access Token (recommended)
+
+Create a PAT in **Settings → Tokens** and pass it to the client.
+Best for scripts, CI pipelines, and MCP servers.
+
+```typescript
+const client = new OmniqClient({
+  baseUrl: 'https://app.omniq.pro/api/v1',
+  token: process.env.OMNIQ_TOKEN,
+});
+```
+
+### Cookie (server-side proxy)
+
+When proxying through a backend that already holds a session cookie,
+forward the `Cookie` header instead:
+
+```typescript
+const client = new OmniqClient({
+  baseUrl: 'https://app.omniq.pro/api/v1',
+  cookieHeader: req.headers.cookie,
+});
+```
+
+### Email / Password
+
+Authenticate programmatically and receive a session. The login response
+sets an `httpOnly` cookie — use `cookieHeader` for subsequent calls.
+
+```typescript
+const client = new OmniqClient({
+  baseUrl: 'https://app.omniq.pro/api/v1',
+});
+
+const { user } = await client.auth.login({
+  email: 'user@example.com',
+  password: 'secret',
+});
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `baseUrl` | `string` | — | API root URL (required) |
+| `token` | `string` | — | Personal Access Token for Bearer auth |
+| `cookieHeader` | `string` | — | Raw `Cookie` header value for server-side proxy |
+| `maxRetries` | `number` | `3` | Retry count for 5xx / network errors |
+
+## Resources
+
+### Auth — `client.auth`
+
+| Method | HTTP | Path | Returns |
+| --- | --- | --- | --- |
+| `login(data)` | `POST` | `/auth/login` | `LoginResponse` |
+| `refresh()` | `POST` | `/auth/refresh` | `{ success: boolean }` |
+| `logout()` | `POST` | `/auth/logout` | `void` |
+| `logoutAll()` | `POST` | `/auth/logout-all` | `void` |
+| `me()` | `GET` | `/auth/me` | `{ user: User }` |
+
+### Projects — `client.projects`
+
+| Method | HTTP | Path | Returns |
+| --- | --- | --- | --- |
+| `list()` | `GET` | `/projects` | `Project[]` |
+| `get(id)` | `GET` | `/projects/:id` | `Project` |
+| `create(data)` | `POST` | `/projects` | `Project` |
+| `update(id, data)` | `PATCH` | `/projects/:id` | `Project` |
+| `delete(id)` | `DELETE` | `/projects/:id` | `void` |
+| `listMembers(projectId)` | `GET` | `/projects/:id/members` | `ProjectMember[]` |
+| `addMember(projectId, data)` | `POST` | `/projects/:id/members` | `void` |
+| `removeMember(projectId, userId)` | `DELETE` | `/projects/:id/members/:userId` | `void` |
+
+```typescript
+const project = await client.projects.create({
+  name: 'Payments',
+  key: 'PAY',
+  description: 'Payment processing service',
+});
+```
+
+### Issues — `client.issues`
+
+| Method | HTTP | Path | Returns |
+| --- | --- | --- | --- |
+| `list(params?)` | `GET` | `/issues` | `PaginatedResponse<Issue>` |
+| `listAll(params?)` | `GET` | `/issues` (auto-paginated) | `AsyncGenerator<Issue>` |
+| `get(id)` | `GET` | `/issues/:id` | `Issue` |
+| `create(data)` | `POST` | `/issues` | `Issue` |
+| `update(id, data)` | `PATCH` | `/issues/:id` | `Issue` |
+| `delete(id)` | `DELETE` | `/issues/:id` | `void` |
+| `updateStatus(id, status)` | `POST` | `/issues/:id/status` | `Issue` |
+| `bulkUpdate(data)` | `POST` | `/issues/bulk` | `Issue[]` |
+| `addComment(issueId, data)` | `POST` | `/issues/:id/comments` | `Comment` |
+| `addLink(issueId, data)` | `POST` | `/issues/:id/links` | `IssueLink` |
+
+```typescript
+const issue = await client.issues.create({
+  projectId: 'proj_1',
+  title: 'Fix login bug',
+  priority: 'high',
+  type: 'bug',
+});
+
+await client.issues.updateStatus(issue.id, 'in_progress');
+```
+
+### Sprints — `client.sprints`
+
+| Method | HTTP | Path | Returns |
+| --- | --- | --- | --- |
+| `list({ projectId })` | `GET` | `/sprints` | `Sprint[]` |
+| `get(id)` | `GET` | `/sprints/:id` | `Sprint` |
+| `create(data)` | `POST` | `/sprints` | `Sprint` |
+| `update(id, data)` | `PATCH` | `/sprints/:id` | `Sprint` |
+| `delete(id)` | `DELETE` | `/sprints/:id` | `void` |
+| `start(id)` | `POST` | `/sprints/:id/start` | `Sprint` |
+| `close(id, transferToSprintId?)` | `POST` | `/sprints/:id/close` | `Sprint` |
+| `burndown(id)` | `GET` | `/sprints/:id/burndown` | `BurndownPoint[]` |
+| `velocity({ projectId })` | `GET` | `/sprints/velocity` | `VelocityData` |
+
+```typescript
+const sprints = await client.sprints.list({ projectId: 'proj_1' });
+const burndown = await client.sprints.burndown(sprints[0].id);
+const velocity = await client.sprints.velocity({ projectId: 'proj_1' });
+
+// Close sprint and transfer undone issues
+await client.sprints.close(sprint.id, nextSprint.id);
+```
+
+### Wiki — `client.wiki`
+
+| Method | HTTP | Path | Returns |
+| --- | --- | --- | --- |
+| `listSpaces({ projectId })` | `GET` | `/wiki/spaces` | `WikiSpace[]` |
+| `createSpace(data)` | `POST` | `/wiki/spaces` | `WikiSpace` |
+| `listPages({ spaceId })` | `GET` | `/wiki/pages` | `WikiPage[]` |
+| `createPage(data)` | `POST` | `/wiki/pages` | `WikiPage` |
+| `updatePage(id, data)` | `PATCH` | `/wiki/pages/:id` | `WikiPage` |
+| `pageVersions(id)` | `GET` | `/wiki/pages/:id/versions` | `WikiPageVersion[]` |
+| `restorePage(pageId, versionId)` | `POST` | `/wiki/pages/:id/restore/:versionId` | `WikiPage` |
+| `search({ projectId, q })` | `GET` | `/wiki/search` | `WikiSearchResult[]` |
+| `templates()` | `GET` | `/wiki/templates` | `WikiTemplate[]` |
+
+```typescript
+const results = await client.wiki.search({
+  projectId: 'proj_1',
+  q: 'onboarding',
+});
+```
+
+### Calendar — `client.calendar`
+
+| Method | HTTP | Path | Returns |
+| --- | --- | --- | --- |
+| `listEvents({ start, end, projectId?, userId? })` | `GET` | `/calendar/events` | `CalendarEvent[]` |
+| `createEvent(data)` | `POST` | `/calendar/events` | `CalendarEvent` |
+| `updateEvent(id, data)` | `PATCH` | `/calendar/events/:id` | `CalendarEvent` |
+| `deleteEvent(id)` | `DELETE` | `/calendar/events/:id` | `void` |
+| `listResources({ start, end, projectId? })` | `GET` | `/calendar/resources` | `CalendarResourceEntity[]` |
+| `exportIcs({ start, end })` | `GET` | `/calendar/export.ics` | `Response` (raw) |
+
+```typescript
+const events = await client.calendar.listEvents({
+  start: '2025-06-01',
+  end: '2025-06-30',
+  projectId: 'proj_1',
+});
+
+const icsResponse = await client.calendar.exportIcs({
+  start: '2025-06-01',
+  end: '2025-06-30',
+});
+const ics = await icsResponse.text();
+```
+
+### AI — `client.ai`
+
+| Method | HTTP | Path | Returns |
+| --- | --- | --- | --- |
+| `chat(data)` | `POST` | `/ai/chat` | `AiChatResponse` |
+| `chatStream(data)` | `POST` | `/ai/chat/stream` | `Response` (raw SSE stream) |
+| `generate(data)` | `POST` | `/ai/generate` | `{ content, tokensUsed }` |
+| `estimate(data)` | `POST` | `/ai/estimate` | `AiEstimateResponse` |
+| `plan(data)` | `POST` | `/ai/plan` | `{ content, tokensUsed }` |
+| `summarize(data)` | `POST` | `/ai/summarize` | `{ content, tokensUsed }` |
+| `insights({ projectId })` | `GET` | `/ai/insights` | `{ content, tokensUsed }` |
+
+```typescript
+const estimate = await client.ai.estimate({
+  title: 'Add OAuth2 login',
+  description: 'Support Google and GitHub OAuth2 flows',
+});
+console.log(`${estimate.storyPoints} SP (${estimate.confidence}% confidence)`);
+
+const reply = await client.ai.chat({
+  message: 'Summarize the current sprint progress',
+  projectId: 'proj_1',
+});
+console.log(reply.content);
+```
+
+### Notifications — `client.notifications`
+
+| Method | HTTP | Path | Returns |
+| --- | --- | --- | --- |
+| `list({ unreadOnly? }?)` | `GET` | `/notifications` | `{ data: Notification[], unreadCount }` |
+| `markRead(id)` | `POST` | `/notifications/:id/read` | `void` |
+| `markAllRead()` | `POST` | `/notifications/read-all` | `void` |
+
+```typescript
+const { data: notifications, unreadCount } = await client.notifications.list({
+  unreadOnly: true,
+});
+
+for (const n of notifications) {
+  await client.notifications.markRead(n.id);
+}
+```
+
+### Tokens — `client.tokens`
+
+| Method | HTTP | Path | Returns |
+| --- | --- | --- | --- |
+| `list()` | `GET` | `/tokens` | `PersonalAccessToken[]` |
+| `create(data)` | `POST` | `/tokens` | `CreatedToken` |
+| `delete(id)` | `DELETE` | `/tokens/:id` | `void` |
+
+```typescript
+const { token } = await client.tokens.create({
+  name: 'CI pipeline',
+  scopes: ['issues:read', 'issues:write'],
+  expiresAt: '2026-12-31T23:59:59Z',
+});
+// Store `token` securely — it is only shown once.
+```
+
+### GitLab — `client.gitlab`
+
+| Method | HTTP | Path | Returns |
+| --- | --- | --- | --- |
+| `listActivity(projectId)` | `GET` | `/git/events` | `GitLabEvent[]` |
+| `linkCommit(issueId, sha, url?)` | `POST` | `/git/commits/link` | `void` |
+
+```typescript
+const events = await client.gitlab.listActivity('proj_1');
+
+await client.gitlab.linkCommit('issue_1', 'abc123def', 'https://gitlab.com/…/commit/abc123def');
+```
+
+## Pagination
+
+Methods returning `PaginatedResponse<T>` include `data`, `total`, `page`, and `limit` fields.
+For convenience, `listAll()` methods return an `AsyncGenerator` that handles page fetching automatically:
+
+```typescript
+for await (const issue of client.issues.listAll({ projectId: 'proj_1' })) {
+  console.log(issue.key, issue.title);
+}
+
+// With filters
+for await (const issue of client.issues.listAll({
+  projectId: 'proj_1',
+  status: 'in_progress',
+  assigneeId: 'user_1',
+})) {
+  process.stdout.write(`${issue.key} `);
+}
+```
+
+The paginator fetches 50 items per page and stops when all items are consumed.
+
+## Error Handling
+
+All API errors throw `OmniqApiError` with `status`, `statusText`, and `body` properties:
+
+```typescript
+import { OmniqClient, OmniqApiError } from '@omniq/sdk';
+
+try {
+  await client.projects.get('nonexistent');
+} catch (error) {
+  if (error instanceof OmniqApiError) {
+    console.error(error.status);     // 404
+    console.error(error.statusText); // "Not Found"
+    console.error(error.body);       // parsed JSON error body
+  }
+}
+```
+
+**Automatic retries** — Server errors (5xx) and network failures are retried up to `maxRetries` times
+(default `3`) with exponential backoff (1 s → 2 s → 4 s, capped at 10 s). Client errors (4xx) are
+never retried and throw immediately.
+
+## TypeScript
+
+The SDK is fully typed. All entity types, input types, enums, and utility types are exported
+from the package root:
+
+```typescript
+import { OmniqClient } from '@omniq/sdk';
+import type {
+  Issue,
+  CreateIssueInput,
+  IssueStatus,
+  IssuePriority,
+  StoryPoints,
+  PaginatedResponse,
+} from '@omniq/sdk';
+
+async function moveToReview(client: OmniqClient, issueId: string): Promise<Issue> {
+  return client.issues.updateStatus(issueId, 'review');
+}
+```
+
+<details>
+<summary>All exported types</summary>
+
+**Enums / Unions** — `Role`, `IssueStatus`, `IssuePriority`, `IssueType`, `StoryPoints`, `SprintStatus`, `CalendarEventType`, `CalendarEventStatus`, `ContentFormat`, `CommentSource`, `NotificationType`, `EntityType`
+
+**Entities** — `User`, `Project`, `Issue`, `Sprint`, `Comment`, `IssueLink`, `WikiSpace`, `WikiPage`, `WikiPageVersion`, `WikiTemplate`, `CalendarEvent`, `CalendarResourceEntity`, `Notification`, `PersonalAccessToken`, `CreatedToken`, `ProjectMember`, `GitLabEvent`, `GitLabCommitLink`
+
+**Inputs** — `LoginInput`, `CreateProjectInput`, `AddMemberInput`, `CreateIssueInput`, `UpdateIssueInput`, `BulkUpdateIssueInput`, `CreateCommentInput`, `CreateIssueLinkInput`, `IssueListParams`, `CreateSprintInput`, `UpdateSprintInput`, `CreateWikiSpaceInput`, `CreateWikiPageInput`, `UpdateWikiPageInput`, `CreateCalendarEventInput`, `UpdateCalendarEventInput`, `CreateTokenInput`, `AiChatInput`, `AiGenerateInput`, `AiEstimateInput`
+
+**Responses** — `LoginResponse`, `AuthTokens`, `AiChatResponse`, `AiEstimateResponse`, `PaginatedResponse<T>`, `BurndownPoint`, `VelocityEntry`, `VelocityData`, `WikiSearchResult`
+
+**Resource classes** — `AuthResource`, `ProjectsResource`, `IssuesResource`, `SprintsResource`, `WikiResource`, `CalendarResource`, `AIResource`, `NotificationsResource`, `TokensResource`, `GitLabResource`
+
+</details>
+
+## License
+
+MIT

package/dist/__tests__/client.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client.test.d.ts.map

package/dist/__tests__/client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/client.test.ts"],"names":[],"mappings":""}