@examplary/sdk 1.0.2 → 1.1.0

package/README.md

@@ -1,25 +1,111 @@
 # Examplary API SDK for TypeScript
 
-This package provides a TypeScript client for the Examplary API, allowing you to interact with the API in a type-safe manner. It includes methods for all API endpoints, as well as type definitions for request and response data.
+A type-safe TypeScript client for the [Examplary API](https://developers.examplary.ai/). One method per API operation, fully typed inputs and responses, axios-backed.
 
 ## Installation
 
-You can install the SDK using npm or yarn:
-
 ```bash
 yarn add @examplary/sdk
 ```
 
-## Usage
+## Quick start
+
+```typescript
+import { Examplary } from "@examplary/sdk";
+
+const client = new Examplary({
+  apiKey: process.env.EXAMPLARY_API_KEY,
+});
+
+// Create a minimal exam with a single open-ended question.
+const exam = await client.exams.create({
+  name: "End-of-term assessment",
+  language: "en",
+  questions: [
+    {
+      type: "single-line-text",
+      title: "What is the capital of France?",
+      scoring: {
+        rubricType: "exact-values",
+        criteria: [{ id: "answer", title: "Paris", points: 1 }],
+      },
+    },
+  ],
+});
+
+console.log(exam.id);
+```
 
-To use the SDK, you need to create an instance of the `ExamplaryClient` class and provide your API key:
+## Calling conventions
+
+Every method takes a single object whose fields combine path, query, and body parameters:
+
+```typescript
+// Path + body merged into one object.
+await client.exams.update({
+  id: exam.id,
+  name: "Updated name",
+});
+
+// Just a string when the operation has a single path parameter.
+const questionType = await client.questionTypes.get("single-line-text");
+```
+
+Each method accepts an optional second argument that extends [axios's request config](https://axios-http.com/docs/req_config) — anything except `method`, `url`, `data`, `params`, `baseURL`:
 
 ```typescript
-import { createExamplaryClient } from "@examplary/sdk";
+await client.exams.list({}, {
+  timeout: 10_000,
+  signal: controller.signal,
+  headers: { "X-Trace-Id": traceId },
+});
+```
+
+Nested resources (e.g. `client.exams.sessions.acceptSuggestion`) rename the parent `id` to `examId` (or `practiceSpaceId`, etc.) for readability:
 
-const client = createExamplaryClient({
-  apiKey: "my-api-key-or-oauth-access-token",
+```typescript
+await client.exams.sessions.acceptSuggestion({
+  examId: exam.id,
+  sessionId,
+  questionId,
 });
+```
+
+## Errors
 
-const { data } = await client.questionTypes.listPublic();
+Failed requests reject with an `ExamplaryError` (an `AxiosError` subclass). The error message is taken from the API response body when available:
+
+```typescript
+import { Examplary, ExamplaryError } from "@examplary/sdk";
+
+try {
+  await client.exams.get("ex_does_not_exist");
+} catch (err) {
+  if (err instanceof ExamplaryError) {
+    console.error(err.message, err.response?.status);
+  }
+}
 ```
+
+## Configuration
+
+`new Examplary(options)` accepts every [axios `CreateAxiosDefaults`](https://axios-http.com/docs/config_defaults) field plus:
+
+| Option    | Type     | Description                                                            |
+| --------- | -------- | ---------------------------------------------------------------------- |
+| `apiKey`  | `string` | Required. API key or OAuth access token. Sent as `Authorization` header. |
+| `baseUrl` | `string` | Override the API host. Defaults to `https://api.examplary.ai`.         |
+
+## Types
+
+Per-operation argument and response types are exported under predictable names:
+
+```typescript
+import type {
+  ExamsCreateArgs,
+  ExamsCreateResponse,
+  QuestionTypesGetArgs,
+} from "@examplary/sdk";
+```
+
+The full OpenAPI surface is also available as `paths`, `operations`, and `components` exports for advanced use.