Skip to main content

Deno SDK

The official Ozwell SDK for Deno runtime, with first-class TypeScript support and no build step required.

Installation​

Import directly from JSR (JavaScript Registry):

import { OzwellClient } from "jsr:@ozwell/api";

Or add to your deno.json:

{
  "imports": {
    "@ozwell/api": "jsr:@ozwell/api@^1.0.0"
  }
}

Then import:

import { OzwellClient } from "@ozwell/api";

Quick Start​

import { OzwellClient } from "jsr:@ozwell/api";

const client = new OzwellClient({
  apiKey: Deno.env.get("OZWELL_API_KEY"),
});

const response = await client.chat.completions.create({
  model: "gpt-4",
  messages: [
    { role: "user", content: "Hello from Deno!" },
  ],
});

console.log(response.choices[0].message.content);

Run with:

deno run --allow-env --allow-net main.ts

Configuration​

Client Options​

import { OzwellClient } from "jsr:@ozwell/api";

const client = new OzwellClient({
  apiKey: Deno.env.get("OZWELL_API_KEY"),
  baseUrl: "https://api.ozwell.ai/v1",  // Optional
  timeout: 30000,                         // Optional
  maxRetries: 3,                          // Optional
});

Environment Variables​

Create a .env file:

OZWELL_API_KEY=ozw_xxxxxxxxxxxxxxxx

Load with --allow-env flag or use dotenv:

import "jsr:@std/dotenv/load";
import { OzwellClient } from "jsr:@ozwell/api";

const client = new OzwellClient({
  apiKey: Deno.env.get("OZWELL_API_KEY"),
});

Permissions​

Deno requires explicit permissions. The SDK needs:

PermissionFlagPurpose
Network--allow-netAPI requests
Environment--allow-envRead API key
Read--allow-readFile uploads (optional)
# Minimal permissions
deno run --allow-env=OZWELL_API_KEY --allow-net=api.ozwell.ai main.ts

# Or allow all needed
deno run --allow-env --allow-net --allow-read main.ts

Chat Completions​

Basic Chat​

const response = await client.chat.completions.create({
  model: "gpt-4",
  messages: [
    { role: "system", content: "You are a Deno expert." },
    { role: "user", content: "What makes Deno different from Node.js?" },
  ],
});

console.log(response.choices[0].message.content);

Streaming​

const stream = await client.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Write a haiku about Deno" }],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) {
    await Deno.stdout.write(new TextEncoder().encode(content));
  }
}
console.log(); // Newline at end

With Parameters​

const response = await client.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Be creative" }],
  temperature: 1.2,
  max_tokens: 500,
  top_p: 0.9,
});

Function Calling​

const response = await client.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "What's the weather in Paris?" }],
  tools: [
    {
      type: "function",
      function: {
        name: "get_weather",
        description: "Get weather for a location",
        parameters: {
          type: "object",
          properties: {
            location: { type: "string", description: "City name" },
          },
          required: ["location"],
        },
      },
    },
  ],
});

const toolCalls = response.choices[0].message.tool_calls;
if (toolCalls) {
  for (const call of toolCalls) {
    console.log("Function:", call.function.name);
    console.log("Args:", call.function.arguments);
  }
}

Embeddings​

const response = await client.embeddings.create({
  model: "text-embedding-ada-002",
  input: "Deno is a secure runtime for JavaScript and TypeScript.",
});

console.log("Vector length:", response.data[0].embedding.length);

Batch Embeddings​

const response = await client.embeddings.create({
  model: "text-embedding-ada-002",
  input: [
    "First document",
    "Second document",
    "Third document",
  ],
});

for (const item of response.data) {
  console.log(`Index ${item.index}: ${item.embedding.length} dimensions`);
}

Files​

Upload File​

const fileContent = await Deno.readFile("./document.pdf");
const blob = new Blob([fileContent], { type: "application/pdf" });

const file = await client.files.create({
  file: blob,
  purpose: "assistants",
});

console.log("Uploaded:", file.id);

Using File Path​

const file = await client.files.upload("./document.pdf", "assistants");
console.log("Uploaded:", file.id);

List and Delete​

// List files
const files = await client.files.list();
for (const file of files.data) {
  console.log(`${file.id}: ${file.filename}`);
}

// Delete file
await client.files.delete("file-abc123");

Error Handling​

import { OzwellClient, OzwellError, RateLimitError } from "jsr:@ozwell/api";

try {
  const response = await client.chat.completions.create({
    model: "gpt-4",
    messages: [{ role: "user", content: "Hello" }],
  });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.error("Rate limited. Retry after:", error.retryAfter);
  } else if (error instanceof OzwellError) {
    console.error("API error:", error.message);
    console.error("Status:", error.status);
  } else {
    throw error;
  }
}

Oak Framework Integration​

Using Oak web framework:

import { Application, Router } from "jsr:@oak/oak";
import { OzwellClient } from "jsr:@ozwell/api";

const client = new OzwellClient({
  apiKey: Deno.env.get("OZWELL_API_KEY"),
});

const router = new Router();

router.post("/api/chat", async (ctx) => {
  const { messages } = await ctx.request.body.json();
  
  const response = await client.chat.completions.create({
    model: "gpt-4",
    messages,
  });
  
  ctx.response.body = {
    message: response.choices[0].message.content,
  };
});

const app = new Application();
app.use(router.routes());
app.use(router.allowedMethods());

console.log("Server running on http://localhost:8000");
await app.listen({ port: 8000 });

Run with:

deno run --allow-env --allow-net server.ts

Fresh Framework Integration​

For Fresh apps, create an API route:

// routes/api/chat.ts
import { Handlers } from "$fresh/server.ts";
import { OzwellClient } from "jsr:@ozwell/api";

const client = new OzwellClient({
  apiKey: Deno.env.get("OZWELL_API_KEY"),
});

export const handler: Handlers = {
  async POST(req) {
    const { messages } = await req.json();
    
    const response = await client.chat.completions.create({
      model: "gpt-4",
      messages,
    });
    
    return new Response(
      JSON.stringify({ message: response.choices[0].message.content }),
      { headers: { "Content-Type": "application/json" } }
    );
  },
};

Hono Framework Integration​

Using Hono:

import { Hono } from "jsr:@hono/hono";
import { OzwellClient } from "jsr:@ozwell/api";

const app = new Hono();
const client = new OzwellClient({
  apiKey: Deno.env.get("OZWELL_API_KEY"),
});

app.post("/api/chat", async (c) => {
  const { messages } = await c.req.json();
  
  const response = await client.chat.completions.create({
    model: "gpt-4",
    messages,
  });
  
  return c.json({ message: response.choices[0].message.content });
});

Deno.serve(app.fetch);

Testing​

// chat_test.ts
import { assertEquals } from "jsr:@std/assert";
import { OzwellClient } from "jsr:@ozwell/api";

Deno.test("chat completion works", async () => {
  const client = new OzwellClient({
    apiKey: Deno.env.get("OZWELL_API_KEY"),
  });
  
  const response = await client.chat.completions.create({
    model: "gpt-4",
    messages: [{ role: "user", content: "Say 'test'" }],
    max_tokens: 10,
  });
  
  assertEquals(response.choices.length, 1);
  assertEquals(typeof response.choices[0].message.content, "string");
});

Run tests:

deno test --allow-env --allow-net

Type Definitions​

All types are exported and available:

import type {
  ChatCompletionRequest,
  ChatCompletionResponse,
  ChatMessage,
  EmbeddingRequest,
  EmbeddingResponse,
  FileObject,
} from "jsr:@ozwell/api";

Comparison with Node.js SDK​

FeatureDenoNode.js
Importjsr:@ozwell/apinpm:@ozwell/api
Env varsDeno.env.get()process.env
File readDeno.readFile()fs.readFileSync()
PermissionsExplicit flagsNone required
TypeScriptNativeRequires build

See Also​