@ancatag/n-r 0.2.26 → 0.2.28

package/README.md

@@ -484,22 +484,93 @@ Get details for a specific model.
 
 **Returns:** `Promise<Model>`
 
-### Type Exports
+### Type Definitions
 
+The SDK provides full TypeScript interfaces for all requests and responses. Here are the core types you'll use most often:
+
+#### `ChatCompletionRequest`
+The main payload for creating a chat completion.
+```typescript
+interface ChatCompletionRequest {
+  model?: string; // Optional: uses project default if omitted
+  messages: ChatMessage[];
+  temperature?: number;
+  top_p?: number;
+  max_tokens?: number;
+  stream?: boolean;
+  stop?: string | string[];
+  
+  // Structured Output & Function Calling
+  response_format?: { type: "json_object" } | any;
+  tools?: any[];
+  tool_choice?: "auto" | "none" | any;
+  
+  // Nova-specific extensions
+  nova?: {
+    skipCache?: boolean;
+    routeConfigId?: string;
+    ragEnabled?: boolean;
+    systemPromptOverride?: string;
+    metadata?: Record<string, any>;
+  };
+}
+```
+
+#### `ChatMessage`
+```typescript
+interface ChatMessage {
+  role: "system" | "user" | "assistant" | "function";
+  content: string;
+  name?: string;
+  function_call?: {
+    name: string;
+    arguments: string;
+  };
+}
+```
+
+#### `ChatCompletionResponse`
+```typescript
+interface ChatCompletionResponse {
+  id: string;
+  object: "chat.completion";
+  created: number;
+  model: string;
+  choices: {
+    index: number;
+    message: {
+      role: "assistant";
+      content: string;
+      function_call?: { name: string; arguments: string; };
+    };
+    finish_reason: "stop" | "length" | "function_call" | "content_filter" | null;
+  }[];
+  usage: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+  nova?: {
+    cacheHit: boolean;
+    cacheLayer?: "hot" | "semantic" | null;
+    tokensSaved: number;
+    responseTimeMs: number;
+    requestId: string;
+  };
+}
+```
+
+#### Exported Types
+You can import any of these types directly from the SDK:
 ```typescript
 import type {
   ChatMessage,
   ChatCompletionRequest,
   ChatCompletionResponse,
   ChatCompletionChunk,
-  ChatCompletionChoice,
-  ChatCompletionUsage,
   Model,
   NovaClientConfig,
-  NovaTransport,
 } from '@ancatag/n-r';
-
-import { NovaError } from '@ancatag/n-r';
 ```
 
 ### Nova-Specific Extensions
@@ -672,6 +743,80 @@ async function chat(
 4. **Generate an API key** (format: `nova_sk_...`)
 5. **Install the SDK** and start saving on token costs!
 
+## Integration Examples
+
+### Express.js
+
+```typescript
+import express from 'express';
+import { NovaClient } from '@ancatag/n-r';
+
+const app = express();
+app.use(express.json());
+
+const nova = new NovaClient({
+  apiKey: process.env.NOVA_API_KEY,
+});
+
+app.post('/api/chat', async (req, res) => {
+  try {
+    const { messages } = req.body;
+    const response = await nova.chat.create({
+      messages,
+      nova: {
+        routeConfigId: process.env.NOVA_ROUTE_CONFIG_ID,
+      }
+    });
+    
+    res.json(response);
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to generate response' });
+  }
+});
+
+app.listen(3000, () => console.log('Server running on port 3000'));
+```
+
+### Next.js App Router (Streaming)
+
+```typescript
+// app/api/chat/route.ts
+import { NovaClient } from '@ancatag/n-r';
+
+// Ensure the Edge runtime if desired, or Node runtime automatically works
+export const maxDuration = 60;
+
+const nova = new NovaClient({
+  apiKey: process.env.NOVA_API_KEY,
+});
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const stream = await nova.chat.createStream({
+    messages,
+    nova: {
+      routeConfigId: process.env.NOVA_ROUTE_CONFIG_ID,
+    }
+  });
+
+  // Create a ReadableStream from the AsyncIterable
+  const readableStream = new ReadableStream({
+    async start(controller) {
+      for await (const chunk of stream) {
+        const text = chunk.choices[0]?.delta?.content || '';
+        if (text) controller.enqueue(new TextEncoder().encode(text));
+      }
+      controller.close();
+    }
+  });
+
+  return new Response(readableStream, {
+    headers: { 'Content-Type': 'text/event-stream' }
+  });
+}
+```
+
 ## Migration from OpenAI
 
 Switching from OpenAI to Nova-route is simple:

package/dist/types.d.ts

@@ -31,6 +31,20 @@ export interface ChatCompletionRequest {
     frequency_penalty?: number;
     logit_bias?: Record<string, number>;
     user?: string;
+    /**
+     * Forced output format for the LLM
+     * Use { type: "json_object" } to force JSON output
+     */
+    response_format?: any;
+    /**
+     * A list of tools the model may call. Usually functions.
+     */
+    tools?: any[];
+    /**
+     * Controls which (if any) tool is called by the model.
+     * e.g., "auto", "none", or a specific tool object
+     */
+    tool_choice?: any;
     nova?: {
         /** Skip cache lookup for this request */
         skipCache?: boolean;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE;QACf,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KAClB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAErC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,WAAW,EAAE,CAAC;IAGxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,eAAe,CAAC,EAAE,GAAG,CAAC;IAEtB;;OAEG;IACH,KAAK,CAAC,EAAE,GAAG,EAAE,CAAC;IAEd;;;OAGG;IACH,WAAW,CAAC,EAAE,GAAG,CAAC;IAGlB,IAAI,CAAC,EAAE;QACN,yCAAyC;QACzC,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,mEAAmE;QACnE,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,mEAAmE;QACnE,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,mDAAmD;QACnD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC/B,kDAAkD;QAClD,oBAAoB,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChC,KAAK,EAAE,mBAAmB,CAAC;IAG3B,IAAI,CAAC,EAAE;QACN,QAAQ,EAAE,OAAO,CAAC;QAClB,UAAU,CAAC,EAAE,KAAK,GAAG,UAAU,GAAG,IAAI,CAAC;QACvC,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;KAClB,CAAC;CACF;AAED,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE;QACR,IAAI,EAAE,WAAW,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,aAAa,CAAC,EAAE;YACf,IAAI,EAAE,MAAM,CAAC;YACb,SAAS,EAAE,MAAM,CAAC;SAClB,CAAC;KACF,CAAC;IACF,aAAa,EAAE,MAAM,GAAG,QAAQ,GAAG,eAAe,GAAG,gBAAgB,GAAG,IAAI,CAAC;CAC7E;AAED,MAAM,WAAW,mBAAmB;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,uBAAuB,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,yBAAyB,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,yBAAyB;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE;QACN,IAAI,CAAC,EAAE,WAAW,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,aAAa,CAAC,EAAE;YACf,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,SAAS,CAAC,EAAE,MAAM,CAAC;SACnB,CAAC;KACF,CAAC;IACF,aAAa,EAAE,MAAM,GAAG,QAAQ,GAAG,eAAe,GAAG,gBAAgB,GAAG,IAAI,CAAC;CAC7E;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,KAAK,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,IAAI,EAAE,MAAM,CAAC;KACb,CAAC;CACF;AAED;;GAEG;AACH,MAAM,WAAW,KAAK;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,SAAU,SAAQ,KAAK;aAGlB,MAAM,CAAC,EAAE,MAAM;aACf,IAAI,CAAC,EAAE,MAAM;aACb,IAAI,CAAC,EAAE,MAAM;gBAH7B,OAAO,EAAE,MAAM,EACC,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,IAAI,CAAC,EAAE,MAAM,YAAA,EACb,IAAI,CAAC,EAAE,MAAM,YAAA;CAK9B"}

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA4JH;;GAEG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAGlB;IACA;IACA;IAJjB,YACC,OAAe,EACC,MAAe,EACf,IAAa,EACb,IAAa;QAE7B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,WAAM,GAAN,MAAM,CAAS;QACf,SAAI,GAAJ,IAAI,CAAS;QACb,SAAI,GAAJ,IAAI,CAAS;QAG7B,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IACzB,CAAC;CACD"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA6KH;;GAEG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAGlB;IACA;IACA;IAJjB,YACC,OAAe,EACC,MAAe,EACf,IAAa,EACb,IAAa;QAE7B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,WAAM,GAAN,MAAM,CAAS;QACf,SAAI,GAAJ,IAAI,CAAS;QACb,SAAI,GAAJ,IAAI,CAAS;QAG7B,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IACzB,CAAC;CACD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancatag/n-r",
-  "version": "0.2.26",
+  "version": "0.2.28",
   "description": "Official Node.js/TypeScript SDK for Nova AI API with route-config-based orchestration",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",