JavaScript/TypeScript SDK

The Papr TypeScript SDK provides a strongly-typed client for interacting with the Papr Memory API from Node.js and browser environments.

TypeScript SDK repository.

Installation

Install the SDK using npm:

npm install @papr/memory

Or using yarn:

yarn add @papr/memory

Requirements

HTTPS: The endpoint requires HTTPS protocol. HTTP connections will fail.
Environment Variable: Set PAPR_MEMORY_API_KEY in your environment before running.
X-Client-Type Header: This is automatically included by the SDK but can be customized if needed.
Authentication: Only use one auth method (X-API-Key takes precedence over Bearer token).

Quick Start

import { Papr } from '@papr/memory';

const client = new Papr({
  xAPIKey: process.env['PAPR_MEMORY_API_KEY'] // Updated parameter name
});

// Add a memory
const memory = await client.memory.add({
  content: "Important meeting notes from today's discussion",
  type: "text",
  metadata: {
    topics: ["meetings", "notes"],
    createdAt: new Date().toISOString()
  }
});

// Search memories with agentic graph (recommended)
const results = await client.memory.search({
  query: "meeting notes from today",
  enable_agentic_graph: true,  // Enable intelligent entity-aware search
  rank_results: false
});

// Add memories in batch
const batchResults = await client.memory.addBatch({
  memories: [
    {
      content: "First memory",
      type: "text",
      metadata: { topics: ["topic1"] }
    },
    {
      content: "Second memory",
      type: "text",
      metadata: { topics: ["topic2"] }
    }
  ]
});

Authentication Methods

The SDK supports three authentication methods:

// API Key Authentication (recommended for most scenarios)
const client = new Papr({
  xAPIKey: "your-api-key"  // Updated parameter name
});

// Bearer Token Authentication
const client = new Papr({
  bearerToken: "your-bearer-token"
});

// Session Token Authentication (for browser-based apps)
const client = new Papr({
  sessionToken: "your-session-token"
});

Key SDK Features

Full TypeScript support with comprehensive type definitions
Promise-based async API
Automatic retries and error handling
Browser and Node.js compatibility
Comprehensive documentation and examples

Main API Operations

// Memory Operations
await client.memory.add({ content: "Memory content", type: "text" });
await client.memory.get("memory_id");
await client.memory.update("memory_id", { content: "Updated content" });
await client.memory.delete("memory_id");
await client.memory.search({ 
  query: "Search query",
  enable_agentic_graph: true  // Recommended for intelligent search
});
await client.memory.addBatch({ memories: [...] });

// User Operations
await client.user.create({ external_id: "user123" });
await client.user.get("user_id");
await client.user.update("user_id", { email: "updated@example.com" });
await client.user.delete("user_id");
await client.user.list();
await client.user.createBatch({ users: [...] });

// Feedback Operations
await client.feedback.submit({
  search_id: "search_id",
  feedbackData: {
    feedbackType: "thumbs_up",
    feedbackSource: "inline"
  }
});
await client.feedback.getByID("feedback_id");
await client.feedback.submitBatch({
  feedback_items: [...]
});

Documentation

For complete documentation, examples, and API reference, visit our TypeScript SDK repository.

Error Handling

The SDK uses typed errors to help you handle different failure cases:

try {
  await client.memory.add({
    content: "Test memory",
    type: "text"
  });
} catch (err) {
  if (err instanceof Papr.APIError) {
    // Handle API errors (400, 401, 403, etc.)
    console.log(err.status, err.message);
  } else if (err instanceof Papr.NetworkError) {
    // Handle network errors
    console.log(err.message);
  }
}

Advanced Usage

Search with Agentic Graph

// HIGHLY RECOMMENDED: Enable agentic graph for intelligent context-aware search
const results = await client.memory.search({
  query: "Find discussions about API performance issues from last month",
  enable_agentic_graph: true,  // Enables intelligent entity relationship navigation
  max_memories: 20,  // Recommended for comprehensive memory coverage
  max_nodes: 15      // Recommended for comprehensive graph entity relationships
});

// Access both memories and graph nodes
results.data.memories.forEach(memory => {
  console.log(`Memory: ${memory.content}`);
});

// Work with graph nodes if available
results.data.nodes.forEach(node => {
  console.log(`Node: ${node.label} - ${node.properties.name || node.properties.id}`);
});

Submitting Feedback

// Submit feedback for a search result
const feedbackResponse = await client.feedback.submit({
  search_id: "search_123",
  feedbackData: {
    feedbackType: "thumbs_up",
    feedbackSource: "inline",
    feedbackText: "This result was exactly what I needed"
  }
});

// Submit batch feedback
const batchResponse = await client.feedback.submitBatch({
  feedback_items: [
    {
      search_id: "search_123",
      feedbackData: {
        feedbackType: "thumbs_up",
        feedbackSource: "inline"
      }
    },
    {
      search_id: "search_456",
      feedbackData: {
        feedbackType: "memory_relevance",
        feedbackSource: "memory_citation",
        feedbackScore: 0.9
      }
    }
  ]
});

Batch Processing with External User IDs

// Adding memories for a specific external user
const batchResponse = await client.memory.addBatch({
  external_user_id: "customer_123456", // Process all memories for this external user
  memories: [
    {
      content: "Customer meeting notes",
      type: "text",
      metadata: {
        topics: ["customer", "meeting"],
        hierarchical_structures: "Customers/Meetings"
      }
    },
    {
      content: "Product feedback from customer",
      type: "text",
      metadata: {
        topics: ["customer", "feedback", "product"],
        hierarchical_structures: "Customers/Feedback"
      }
    }
  ],
  batch_size: 10
});

console.log(`Successful: ${batchResponse.total_successful}, Failed: ${batchResponse.total_failed}`);