### Develop Next.js Example

Source: https://github.com/jamsocket/y-sweet/blob/main/js-pkg/README.md

Execute this command from the repository root to start the development server for the Next.js example.

```bash
npm run dev -w examples/nextjs
```

--------------------------------

### Run Y-Sweet NextJS Demo

Source: https://github.com/jamsocket/y-sweet/blob/main/examples/nextjs/README.md

Commands to install dependencies and start the development server with a connection string.

```bash
npm install
```

```bash
CONNECTION_STRING=<your-connection-string> npm run dev
```

--------------------------------

### Start Development Server

Source: https://github.com/jamsocket/y-sweet/blob/main/examples/vanilla/README.md

Execute this command to start the development server for the VanillaJS project.

```bash
npm run dev
```

--------------------------------

### Install @y-sweet/sdk

Source: https://github.com/jamsocket/y-sweet/blob/main/js-pkg/sdk/README.md

Use npm to install the SDK package.

```bash
npm install @y-sweet/sdk
```

--------------------------------

### Install Dependencies

Source: https://github.com/jamsocket/y-sweet/blob/main/js-pkg/README.md

Run this command from the repository root to install all project dependencies.

```bash
npm install
```

--------------------------------

### Sync development environment

Source: https://github.com/jamsocket/y-sweet/blob/main/python/README.md

Sets up the virtual environment and installs dependencies using uv.

```bash
uv sync --dev
```

--------------------------------

### Install @y-sweet/react

Source: https://github.com/jamsocket/y-sweet/blob/main/js-pkg/react/README.md

Command to install the library via npm.

```bash
npm install @y-sweet/react
```

--------------------------------

### Start Y-Sweet Server

Source: https://github.com/jamsocket/y-sweet/blob/main/examples/vanilla/README.md

In a separate terminal, start the Y-Sweet server using your connection string. Replace `<your-connection-string>` with your actual connection string.

```bash
CONNECTION_STRING=<your-connection-string> npm run server
```

--------------------------------

### Install uv project manager

Source: https://github.com/jamsocket/y-sweet/blob/main/python/README.md

Installs the uv project manager on Mac or Linux systems.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Run Local Y-Sweet Server

Source: https://github.com/jamsocket/y-sweet/blob/main/docs/running.md

Use this command to quickly start a local Y-Sweet server. It downloads the server if not already present.

```bash
npx y-sweet@latest serve
```

--------------------------------

### Install @y-sweet/client

Source: https://github.com/jamsocket/y-sweet/blob/main/js-pkg/client/README.md

Use this command to add the @y-sweet/client package to your project dependencies.

```bash
npm install @y-sweet/client
```

--------------------------------

### Run Y-Sweet Server Locally

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Start a local Y-Sweet development server. Use in-memory storage by default, or specify a path for file system persistence or an S3 URL for S3 storage.

```bash
npx y-sweet@latest serve
```

```bash
npx y-sweet@latest serve /path/to/data
```

```bash
npx y-sweet@latest serve s3://my-bucket/y-sweet-data
```

```bash
npx y-sweet@latest serve --auth <private-key> /path/to/data
```

--------------------------------

### Manage User Presence with React Hooks

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Use `usePresence` to get other users' presence data and `usePresenceSetter` to update local user presence. Include self in presence maps with `{ includeSelf: true }`. Requires setup with `useYjsProvider`.

```tsx
import {
  usePresence,
  usePresenceSetter,
  useAwareness,
  useConnectionStatus,
  useHasLocalChanges,
  useYjsProvider
} from '@y-sweet/react'

type UserPresence = {
  name: string
  color: string
  cursor: { x: number; y: number } | null
}

function CollaborativeCanvas() {
  // Get other users' presence (excludes self by default)
  const others = usePresence<UserPresence>()

  // Get presence setter
  const setPresence = usePresenceSetter<UserPresence>()

  // Include self in presence map
  const allUsers = usePresence<UserPresence>({ includeSelf: true })

  // Set local user's presence
  useEffect(() => {
    setPresence({
      name: 'Alice',
      color: '#ff0000',
      cursor: null
    })
  }, [])

  const handleMouseMove = (e: React.MouseEvent) => {
    setPresence({
      name: 'Alice',
      color: '#ff0000',
      cursor: { x: e.clientX, y: e.clientY }
    })
  }

  return (
    <div onMouseMove={handleMouseMove}>
      {/* Render other users' cursors */}
      {Array.from(others.entries()).map(([clientId, presence]) => (
        presence.cursor && (
          <div
            key={clientId}
            style={{
              position: 'absolute',
              left: presence.cursor.x,
              top: presence.cursor.y,
              backgroundColor: presence.color
            }}
          >
            {presence.name}
          </div>
        )
      ))}
    </div>
  )
}
```

```tsx
function ConnectionIndicator() {
  // Get connection status
  const status = useConnectionStatus()
  // 'offline' | 'connecting' | 'handshaking' | 'connected' | 'error'

  // Check for unsaved local changes
  const hasLocalChanges = useHasLocalChanges()

  return (
    <div>
      <span>Status: {status}</span>
      {hasLocalChanges && <span>Saving...</span>}
    </div>
  )
}
```

```tsx
function AdvancedUsage() {
  // Access raw provider for advanced use cases
  const provider = useYjsProvider()

  // Access raw awareness
  const awareness = useAwareness()

  return (
    <button onClick={() => provider.disconnect()}>
      Disconnect
    </button>
  )
}
```

--------------------------------

### Run Local Y-Sweet Server with Data Persistence

Source: https://github.com/jamsocket/y-sweet/blob/main/docs/running.md

Specify a directory to persist Y-Sweet data to disk. If the path starts with `s3://`, it will use S3-compatible storage.

```bash
npx y-sweet@latest serve /path/to/data
```

--------------------------------

### Initialize and Use DocumentManager in TypeScript

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Demonstrates initializing the DocumentManager with a connection string and performing operations like creating documents, getting client tokens, and reading/writing document content.

```typescript
import { DocumentManager } from '@y-sweet/sdk'
import * as Y from 'yjs'

// Initialize with connection string (ys:// for http, yss:// for https)
const manager = new DocumentManager('ys://localhost:8080')
// With authentication: 'ys://server-token@localhost:8080'

// Create a new document
const result = await manager.createDoc()
console.log(result.docId) // 'abc123xyz'

// Create document with specific ID
const doc = await manager.createDoc('my-custom-doc-id')

// Get client token for a document
const clientToken = await manager.getClientToken('my-doc-id')
// { url: 'ws://...', baseUrl: 'http://...', docId: '...', token: '...' }

// Get or create document and token in one call
const token = await manager.getOrCreateDocAndToken('optional-doc-id')

// Get client token with authorization options
const readOnlyToken = await manager.getClientToken('my-doc-id', {
  authorization: 'read-only',
  validForSeconds: 7200
})

// Read document as Yjs update
const update = await manager.getDocAsUpdate('my-doc-id')
const doc = new Y.Doc()
Y.applyUpdate(doc, update)

// Update document with Yjs update
const newDoc = new Y.Doc()
newDoc.getMap('data').set('key', 'value')
const updateBytes = Y.encodeStateAsUpdate(newDoc)
await manager.updateDoc('my-doc-id', updateBytes)

// Create document with initial content
const initialDoc = new Y.Doc()
initialDoc.getText('content').insert(0, 'Hello World')
const newDocResult = await manager.createDocWithContent(
  Y.encodeStateAsUpdate(initialDoc)
)

// Check storage health
const storeStatus = await manager.checkStore()
if (!storeStatus.ok) {
  console.error('Storage error:', storeStatus.error)
}
```

--------------------------------

### Implement Collaborative Editor Component

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Full example of a collaborative page component using Y-Sweet React hooks for state management and presence tracking.

```tsx
// app/collaborative-editor/page.tsx
import { YDocProvider } from '@y-sweet/react'
import { CollaborativeEditor } from './CollaborativeEditor'

function generateId() {
  return Math.random().toString(36).substring(2, 15)
}

export default function Page({ searchParams }: { searchParams: { doc?: string } }) {
  const docId = searchParams.doc ?? generateId()

  return (
    <YDocProvider
      docId={docId}
      authEndpoint="/api/auth"
      setQueryParam="doc"
      offlineSupport={true}
    >
      <CollaborativeEditor />
    </YDocProvider>
  )
}

// CollaborativeEditor.tsx
'use client'

import {
  useMap,
  usePresence,
  usePresenceSetter,
  useConnectionStatus,
  useHasLocalChanges
} from '@y-sweet/react'
import { useEffect, useState } from 'react'

type Presence = {
  name: string
  color: string
}

export function CollaborativeEditor() {
  const data = useMap<string>('editor-data')
  const others = usePresence<Presence>()
  const setPresence = usePresenceSetter<Presence>()
  const status = useConnectionStatus()
  const hasUnsavedChanges = useHasLocalChanges()
  const [userName] = useState(`User-${Math.random().toString(36).slice(2, 6)}`)

  useEffect(() => {
    setPresence({
      name: userName,
      color: `hsl(${Math.random() * 360}, 70%, 50%)`
    })
  }, [userName, setPresence])

  return (
    <div>
      <header>
        <span>
          {status === 'connected' ? '🟢' : '🔴'} {status}
        </span>
        {hasUnsavedChanges && <span>Saving...</span>}
        <span>
          Online: {Array.from(others.values()).map(p => p.name).join(', ')}
        </span>
      </header>

      <main>
        <input
          value={data.get('title') ?? ''}
          onChange={(e) => data.set('title', e.target.value)}
          placeholder="Document title"
        />
        <textarea
          value={data.get('content') ?? ''}
          onChange={(e) => data.set('content', e.target.value)}
          placeholder="Start typing..."
        />
      </main>
    </div>
  )
}
```

--------------------------------

### YDocProvider Component Setup

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Use YDocProvider to create and manage Yjs documents and YSweetProviders, making them available via React context. Configure document ID, authentication endpoint, and optional features like offline support and debugger links.

```tsx
import { YDocProvider } from '@y-sweet/react'

function App() {
  return (
    <YDocProvider
      docId="my-document-id"
      authEndpoint="/api/auth"
      offlineSupport={true}
      showDebuggerLink={false}
      setQueryParam="doc"  // Sets URL param ?doc=my-document-id
      warnOnClose={true}
    >
      <CollaborativeEditor />
    </YDocProvider>
  )
}

// With async auth function
function AppWithCustomAuth() {
  const getToken = async () => {
    const res = await fetch('/api/custom-auth', { method: 'POST' })
    return res.json()
  }

  return (
    <YDocProvider docId="doc-123" authEndpoint={getToken}>
      <CollaborativeEditor />
    </YDocProvider>
  )
}
```

--------------------------------

### GET /d/{docId}/as-update

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Retrieves the entire document state as a Yjs update binary format.

```APIDOC
## GET /d/{docId}/as-update

### Description
Retrieves the entire document state as a Yjs update binary format.

### Method
GET

### Endpoint
/d/{docId}/as-update

### Parameters
#### Path Parameters
- **docId** (string) - Required - The unique identifier for the document.

### Response
#### Success Response (200)
- **binary** (blob) - The document state as a Yjs update.
```

--------------------------------

### Get Document as Yjs Update

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Retrieve the entire document state in Yjs update binary format using the client token. This binary data can then be applied to a Yjs document in JavaScript.

```bash
# Get document as Yjs update (binary format)
curl -X GET http://localhost:8080/d/my-document-id/as-update \
  -H "Authorization: Bearer <client-token>" \
  -o document.bin

# Apply the update to a Yjs document (JavaScript)
# import * as Y from 'yjs'
# const doc = new Y.Doc()
# doc.transact(() => {
#   Y.applyUpdate(doc, updateBytes)
# })
```

--------------------------------

### useArray Hook for Shared Y.Array Data

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Manage shared Y.Array data structures for ordered lists. Use methods like push, delete, and get to interact with the array. Each item in the array can be a complex Yjs type like Y.Map.

```tsx
import { useArray } from '@y-sweet/react'
import * as Y from 'yjs'

function ToDoList() {
  // Get a shared Y.Array
  const items = useArray<Y.Map<any>>('todolist')

  const addItem = (text: string) => {
    const item = new Y.Map([
      ['text', text],
      ['done', false]
    ])
    items.push([item])
  }

  const toggleItem = (index: number) => {
    const item = items.get(index)
    item.set('done', !item.get('done'))
  }

  const deleteItem = (index: number) => {
    items.delete(index, 1)
  }

  return (
    <ul>
      {items.map((item, index) => (
        <li key={index}>
          <input
            type="checkbox"
            checked={item.get('done')}
            onChange={() => toggleItem(index)}
          />
          <span>{item.get('text')}</span>
          <button onClick={() => deleteItem(index)}>Delete</button>
        </li>
      ))}
      <button onClick={() => addItem('New task')}>Add Item</button>
    </ul>
  )
}
```

--------------------------------

### Create a New Y-Sweet Project

Source: https://github.com/jamsocket/y-sweet/blob/main/js-pkg/create-y-sweet-app/README.md

Run this command to initialize a new project with create-y-sweet-app. You will be prompted to choose a project name and a framework.

```sh
npx create-y-sweet-app@latest
```

--------------------------------

### Run Y-Sweet Server with Docker

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Deploy the Y-Sweet server using Docker by mapping the container's port 8080 to the host.

```bash
docker run -p 8080:8080 ghcr.io/jamsocket/y-sweet:latest
```

--------------------------------

### Connect to Y-Sweet on the client

Source: https://github.com/jamsocket/y-sweet/blob/main/README.md

Initialize a Yjs document and link it to the Y-Sweet server using a provider. Ensure the auth endpoint is configured to return a valid client token.

```js
import * as Y from 'yjs';
import { createYjsProvider } from '@y-sweet/client';

// Create the Yjs doc and link it to the Y-Sweet server:
const doc = new Y.Doc();
const docId = 'my-doc-id';
createYjsProvider(doc, docId, '/api/my-auth-endpoint');

// Now use the doc like a normal Yjs doc!
let mySharedMap = doc.getMap('thing');
mySharedMap.set("foo", 123);

// Update your UI based on `mySharedMap` changes like this, for example:
mySharedMap.observe((event) => {
  event.keysChanged.forEach((key) => {
    // do whatever you want based on the detected change:
    yourUpdateFunction(key, mySharedMap.get(key));
  });
});
```

--------------------------------

### Develop JS Packages

Source: https://github.com/jamsocket/y-sweet/blob/main/js-pkg/README.md

Run these commands in two separate terminal tabs from the repository root to develop the SDK and React packages concurrently.

```bash
npm run dev -w js-pkg/sdk
```

```bash
npm run dev -w js-pkg/react
```

--------------------------------

### Create YjsProvider with Y-Sweet Client in TypeScript

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Shows how to create a YSweetProvider to sync a Yjs document with a Y-Sweet server, including options for authentication, offline support, and connection management.

```typescript
import * as Y from 'yjs'
import { createYjsProvider, YSweetProvider } from '@y-sweet/client'

// Create Yjs document and connect to Y-Sweet
const doc = new Y.Doc()
const docId = 'my-document-id'

// Connect using auth endpoint URL (fetches token automatically)
const provider = createYjsProvider(doc, docId, '/api/auth')

// Connect using async function that returns ClientToken
const provider2 = createYjsProvider(doc, docId, async () => {
  const response = await fetch('/api/auth', {
    method: 'POST',
    body: JSON.stringify({ docId }),
    headers: { 'Content-Type': 'application/json' }
  })
  return response.json()
})

// With additional options
const provider3 = createYjsProvider(doc, docId, '/api/auth', {
  connect: true,              // Auto-connect on creation (default: true)
  offlineSupport: true,       // Enable IndexedDB for offline support
  showDebuggerLink: false,    // Hide debugger URL in console
  warnOnClose: true           // Warn when closing with unsaved changes
})

// Listen to connection status changes
provider.on('connection-status', (status) => {
  // status: 'offline' | 'connecting' | 'handshaking' | 'connected' | 'error'
  console.log('Connection status:', status)
})

// Check for local unsaved changes
provider.on('local-changes', (hasChanges) => {
  console.log('Has unsaved changes:', hasChanges)
})

// Manual connect/disconnect
provider.disconnect()
await provider.connect()

// Check sync status
console.log('Connected:', provider.status === 'connected')
console.log('Has local changes:', provider.hasLocalChanges)

// Access awareness for presence features
const awareness = provider.awareness
awareness.setLocalState({ user: 'Alice', cursor: { x: 100, y: 200 } })

// Clean up
provider.destroy()
```

--------------------------------

### Format code

Source: https://github.com/jamsocket/y-sweet/blob/main/python/README.md

Formats the codebase using ruff before committing changes.

```bash
uv run ruff format
```

--------------------------------

### POST /doc/new

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Creates a new document on the Y-Sweet server. If a docId is provided and already exists, it performs a no-op.

```APIDOC
## POST /doc/new

### Description
Creates a new document on the Y-Sweet server. If a docId is provided and a document with that ID already exists, this is a no-op.

### Method
POST

### Endpoint
/doc/new

### Parameters
#### Request Body
- **docId** (string) - Optional - The unique identifier for the document.

### Request Example
{
  "docId": "my-document-id"
}

### Response
#### Success Response (200)
- **docId** (string) - The ID of the created document.

#### Response Example
{
  "docId": "abc123xyz"
}
```

--------------------------------

### Create New Document - Y-Sweet API

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Use the Document Management API to create a new document. Provide a specific docId or allow the server to auto-generate one. Requires a server token for authentication.

```bash
# Create a new document with auto-generated ID
curl -X POST http://localhost:8080/doc/new \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <server-token>"

# Response:
# { "docId": "abc123xyz" }

# Create a document with a specific ID
curl -X POST http://localhost:8080/doc/new \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <server-token>" \
  -d '{"docId": "my-document-id"}'

# Response:
# { "docId": "my-document-id" }
```

--------------------------------

### Publish Y-Sweet Packages

Source: https://github.com/jamsocket/y-sweet/blob/main/releaser/README.md

Execute this command to publish updated packages to their respective registries. It verifies if binaries have been published and compares package versions before publishing.

```bash
cargo run -- publish
```

--------------------------------

### Manage documents on the server

Source: https://github.com/jamsocket/y-sweet/blob/main/README.md

Use the DocumentManager SDK to generate client tokens for authorized users. The CONNECTION_STRING is required to initialize the manager.

```js
import { DocumentManager } from '@y-sweet/sdk';

// Pass in a CONNECTION_STRING, which you can get from a Y-Sweet service in the Jamsocket dashboard or from running npx y-sweet@latest serve locally
const manager = new DocumentManager(CONNECTION_STRING);

// create an endpoint that auths your user and returns a Y-Sweet client token
export async function POST(request) {
  // in a production app, you'd want to authenticate the user
  // and make sure they have access to the given doc
  const body = await request.json();
  const docId = body.docId;
  const clientToken = await manager.getOrCreateDocAndToken(docId);
  return Response.json(clientToken);
}
```

--------------------------------

### Implement user presence with React hooks

Source: https://github.com/jamsocket/y-sweet/blob/main/js-pkg/react/README.md

Uses usePresence to retrieve other users' data and usePresenceSetter to broadcast the current user's mouse position and color.

```tsx
'use client'

import { usePresence, usePresenceSetter } from '@y-sweet/react'
import { useCallback, useRef } from 'react'

const COLORS = ['bg-red-500', 'bg-blue-500', 'bg-green-500', 'bg-purple-500', 'bg-pink-500']

type Presence = { x: number; y: number; color: string }

export function Presence() {
  const myColor = useRef(COLORS[Math.floor(Math.random() * COLORS.length)])
  const presence = usePresence<Presence>()
  const setPresence = usePresenceSetter<Presence>()

  const updatePresence = useCallback(
    (e: React.MouseEvent<HTMLDivElement>) => {
      setPresence({
        x: e.clientX - e.currentTarget.offsetLeft,
        y: e.clientY - e.currentTarget.offsetTop,
        color: myColor.current,
      })
    },
    [setPresence],
  )

  return (
    <div
      className="border-blue-400 border relative overflow-hidden w-[500px] h-[500px]"
      onMouseMove={updatePresence}
    >
      {Array.from(presence.entries()).map(([key, value]) => (
        <div
          key={key}
          className={`absolute rounded-full ${value.color}`}
          style={{ left: value.x - 6, top: value.y - 8, width: 10, height: 10 }}
        />
      ))}
    </div>
  )
}
```

--------------------------------

### Bump Y-Sweet Version

Source: https://github.com/jamsocket/y-sweet/blob/main/releaser/README.md

Use this command to initiate the version bumping process. It prompts for a bump type (patch, minor, major), updates versions across all packages, creates a new git branch, and pushes a PR.

```bash
cargo run -- bump
```

--------------------------------

### Manage Documents with Python SDK

Source: https://context7.com/jamsocket/y-sweet/llms.txt

The Python SDK allows backend applications to manage Yjs documents. Initialize `DocumentManager` with a connection string. Supports creating, retrieving, and updating documents, as well as generating client tokens and checking storage health.

```python
from y_sweet_sdk import DocumentManager, get_or_create_doc_and_token

# Initialize with connection string
manager = DocumentManager('ys://localhost:8080')
# With authentication: 'ys://server-token@localhost:8080'

# Create a new document
result = manager.create_doc()
print(result['docId'])  # 'abc123xyz'

# Create with specific ID
doc = manager.create_doc('my-custom-doc-id')

# Get client token for a document
token = manager.get_client_token('my-doc-id')
# {'url': 'ws://...', 'baseUrl': 'http://...', 'docId': '...', 'token': '...'}

# Get or create document and token in one call
token = manager.get_or_create_doc_and_token('optional-doc-id')

# Get WebSocket URL for direct client connections
ws_url = manager.get_websocket_url('my-doc-id')
# 'ws://localhost:8080/d/my-doc-id/ws?token=...'

# Read document as Yjs update bytes
update_bytes = manager.get_doc_as_update('my-doc-id')

# Update document with Yjs update bytes
manager.update_doc('my-doc-id', update_bytes)

# Check storage health
status = manager.check_store()
if not status['ok']:
    print(f"Storage error: {status['error']}")

# Convenience functions (without instantiating manager)
token = get_or_create_doc_and_token('ys://localhost:8080', 'my-doc-id')
```

--------------------------------

### Y-Sweet Server Health Checks

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Perform health checks on the Y-Sweet server. The '/ready' endpoint provides a basic readiness check, while '/check_store' verifies connectivity to the storage backend.

```bash
# Basic server readiness check
curl http://localhost:8080/ready
# Response: { "ok": true }

# Check storage backend connectivity
curl -X POST http://localhost:8080/check_store \
  -H "Authorization: Bearer <server-token>"
# Response: { "ok": true }
# Or on failure: { "ok": false, "error": "Connection refused" }
```

--------------------------------

### Create Next.js Authentication Endpoints

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Endpoints for generating client tokens for document access. Includes both standard and read-only access patterns.

```typescript
// app/api/auth/route.ts
import { getOrCreateDocAndToken } from '@y-sweet/sdk'
import { NextResponse } from 'next/server'

const CONNECTION_STRING = process.env.CONNECTION_STRING ?? 'ys://127.0.0.1:8080'

const CORS_HEADERS = {
  'access-control-allow-origin': '*',
  'access-control-allow-methods': 'POST',
  'access-control-allow-headers': 'content-type',
}

export async function OPTIONS(request: Request) {
  return new Response(null, { status: 204, headers: CORS_HEADERS })
}

export async function POST(request: Request) {
  // In production, validate user authentication here
  const { docId } = await request.json()

  // Create or get document and generate client token
  const clientToken = await getOrCreateDocAndToken(CONNECTION_STRING, docId)

  return NextResponse.json(clientToken, { headers: CORS_HEADERS })
}

// app/api/auth-readonly/route.ts - Read-only access
import { DocumentManager } from '@y-sweet/sdk'

export async function POST(request: Request) {
  const { docId } = await request.json()
  const manager = new DocumentManager(CONNECTION_STRING)

  // Ensure document exists
  await manager.createDoc(docId)

  // Generate read-only token
  const clientToken = await manager.getClientToken(docId, {
    authorization: 'read-only',
    validForSeconds: 3600
  })

  return NextResponse.json(clientToken)
}
```

--------------------------------

### createYjsProvider

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Creates a Yjs provider for real-time synchronization of Yjs documents with the Y-Sweet server over WebSockets.

```APIDOC
## createYjsProvider

### Description
Creates a `YSweetProvider` that synchronizes a Yjs document with the Y-Sweet server over WebSocket. It manages connection, reconnection, and the sync protocol.

### Usage

```typescript
import * as Y from 'yjs'
import { createYjsProvider, YSweetProvider } from '@y-sweet/client'

const doc = new Y.Doc()
const docId = 'my-document-id'

// Connect using an authentication endpoint URL
const provider = createYjsProvider(doc, docId, '/api/auth')

// Connect using an async function that returns a ClientToken
const provider2 = createYjsProvider(doc, docId, async () => {
  const response = await fetch('/api/auth', {
    method: 'POST',
    body: JSON.stringify({ docId }),
    headers: { 'Content-Type': 'application/json' }
  })
  return response.json()
})

// With additional options
const provider3 = createYjsProvider(doc, docId, '/api/auth', {
  connect: true,              // Auto-connect on creation (default: true)
  offlineSupport: true,       // Enable IndexedDB for offline support
  showDebuggerLink: false,    // Hide debugger URL in console
  warnOnClose: true           // Warn when closing with unsaved changes
})
```

### Parameters

- **doc** (Y.Doc) - Required - The Yjs document to synchronize.
- **docId** (string) - Required - The ID of the document on the Y-Sweet server.
- **authEndpoint** (string | () => Promise<ClientToken>) - Required - The URL of the authentication endpoint or an async function that returns a `ClientToken`.
- **options** (object) - Optional - Configuration options for the provider.
  - **connect** (boolean) - Auto-connect on creation (default: `true`).
  - **offlineSupport** (boolean) - Enable IndexedDB for offline support (default: `false`).
  - **showDebuggerLink** (boolean) - Hide debugger URL in console (default: `true`).
  - **warnOnClose** (boolean) - Warn when closing with unsaved changes (default: `false`).

### Events

- **`connection-status`**: Emitted when the connection status changes.
  - **Parameters**: `status` ('offline' | 'connecting' | 'handshaking' | 'connected' | 'error').
- **`local-changes`**: Emitted when there are local unsaved changes.
  - **Parameters**: `hasChanges` (boolean).

### Methods

- **`disconnect()`**: Disconnects the provider from the server.
- **`connect()`**: Connects the provider to the server.
- **`destroy()`**: Cleans up the provider and disconnects.

### Properties

- **`status`**: Current connection status ('offline' | 'connecting' | 'handshaking' | 'connected' | 'error').
- **`hasLocalChanges`**: Boolean indicating if there are unsaved local changes.
- **`awareness`**: Yjs awareness API for presence features.

```

--------------------------------

### Generate Client Token - Y-Sweet API

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Generate a client token for accessing a specific document. Specify the authorization level ('full' or 'read-only') and optionally set an expiration time in seconds.

```bash
# Generate a client token for a document
curl -X POST http://localhost:8080/doc/my-document-id/auth \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <server-token>" \
  -d '{"authorization": "full"}'

# Response:
# {
#   "url": "ws://localhost:8080/d/my-document-id/ws",
#   "baseUrl": "http://localhost:8080/d/my-document-id",
#   "docId": "my-document-id",
#   "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
# }

# Generate a read-only token with expiration
curl -X POST http://localhost:8080/doc/my-document-id/auth \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <server-token>" \
  -d '{"authorization": "read-only", "validForSeconds": 3600}'
```

--------------------------------

### Run tests

Source: https://github.com/jamsocket/y-sweet/blob/main/python/README.md

Executes the test suite using pytest within the managed virtual environment.

```bash
uv run pytest
```

--------------------------------

### Use Y-Sweet SDK Convenience Functions in TypeScript

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Provides standalone functions for common Y-Sweet operations like creating/getting documents and tokens, without needing to instantiate the DocumentManager class.

```typescript
import {
  getOrCreateDocAndToken,
  getClientToken,
  createDoc
} from '@y-sweet/sdk'

const CONNECTION_STRING = 'ys://localhost:8080'

// Create or get existing document and generate client token
const clientToken = await getOrCreateDocAndToken(
  CONNECTION_STRING,
  'my-doc-id'
)

// Get token for existing document
const token = await getClientToken(CONNECTION_STRING, 'existing-doc-id')

// Create a new document
const newDoc = await createDoc(CONNECTION_STRING, 'new-doc-id')
```

--------------------------------

### Connect to a Y-Sweet document

Source: https://github.com/jamsocket/y-sweet/blob/main/python/README.md

Retrieves a WebSocket URL using the DocumentManager and connects to the document using ypy-websocket.

```python
from y_sweet_sdk import DocumentManager

# Get the websocket url for a document.
doc = DocumentManager('ys://localhost:8080')
url = doc.get_websocket_url('my-document-id')

# Connect to the document using y_py and ypy_websocket.
# (Based on: https://davidbrochart.github.io/ypy-websocket/usage/client/)
from ypy_websocket import WebsocketProvider
import y_py as Y
from websockets import connect
import asyncio

ydoc = Y.YDoc()

# Simple example: log the array "todolist" to stdout every time it changes.
data = ydoc.get_array("todolist")
def data_changed(event: Y.AfterTransactionEvent):
    print(f"data changed: {data.to_json()}")

data.observe_deep(data_changed)

async with (
    connect(url) as websocket,
    WebsocketProvider(ydoc, websocket),
):
    await asyncio.Future()  # run forever
```

--------------------------------

### POST /doc/{docId}/auth

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Generates a client token for accessing a document, including WebSocket URL and authentication credentials.

```APIDOC
## POST /doc/{docId}/auth

### Description
Generates a client token for accessing a document. The token includes the WebSocket URL and authentication credentials needed for clients to connect.

### Method
POST

### Endpoint
/doc/{docId}/auth

### Parameters
#### Path Parameters
- **docId** (string) - Required - The unique identifier for the document.

#### Request Body
- **authorization** (string) - Required - Authorization level (e.g., "full" or "read-only").
- **validForSeconds** (integer) - Optional - Token expiration time in seconds.

### Request Example
{
  "authorization": "read-only",
  "validForSeconds": 3600
}

### Response
#### Success Response (200)
- **url** (string) - WebSocket URL for synchronization.
- **baseUrl** (string) - Base URL for document operations.
- **docId** (string) - The document ID.
- **token** (string) - The generated JWT token.

#### Response Example
{
  "url": "ws://localhost:8080/d/my-document-id/ws",
  "baseUrl": "http://localhost:8080/d/my-document-id",
  "docId": "my-document-id",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

--------------------------------

### Convenience Functions

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Standalone functions for common YSweet operations without needing to instantiate the DocumentManager class.

```APIDOC
## Convenience Functions

### Description
Provides standalone functions for common YSweet operations, simplifying usage without requiring a `DocumentManager` instance.

### Functions

#### `getOrCreateDocAndToken(connectionString: string, docId?: string)`
Creates or gets an existing document and generates a client token.

- **Parameters**:
  - **connectionString** (string) - Required - The YSweet connection string (e.g., 'ys://localhost:8080').
  - **docId** (string) - Optional - The ID of the document.
- **Response**: Client token object.

#### `getClientToken(connectionString: string, docId: string)`
Gets a client token for an existing document.

- **Parameters**:
  - **connectionString** (string) - Required - The YSweet connection string.
  - **docId** (string) - Required - The ID of the document.
- **Response**: Client token object.

#### `createDoc(connectionString: string, docId?: string)`
Creates a new document.

- **Parameters**:
  - **connectionString** (string) - Required - The YSweet connection string.
  - **docId** (string) - Optional - The desired ID for the new document.
- **Response**: Document creation result object.

```

--------------------------------

### Use useText for shared strings

Source: https://github.com/jamsocket/y-sweet/blob/main/js-pkg/react/README.md

Access a Yjs Y.Text to store and synchronize string data.

```tsx
const yText = useText('text')
```

--------------------------------

### Use useMap for shared objects

Source: https://github.com/jamsocket/y-sweet/blob/main/js-pkg/react/README.md

Access a Yjs Y.Map to store key-value pairs, such as a grid of colors.

```tsx
const items = useMap<string>('colorgrid')

items.delete(key)
items.set(`${x},${y}`, color)
```

--------------------------------

### Implement Server-Side Token Generation in Next.js

Source: https://github.com/jamsocket/y-sweet/blob/main/js-pkg/sdk/README.md

Use getOrCreateDocAndToken to retrieve a client token for a specific document, then pass it to the YDocProvider component.

```tsx
import { YDocProvider } from '@y-sweet/react'
import { getOrCreateDocAndToken } from '@y-sweet/sdk'

type HomeProps = {
  searchParams: Record<string, string>
}

export default async function Home({ searchParams }: HomeProps) {
    // Point to a local or production y-sweet server.
    const connectionString = "ys://localhost:8080"

    const clientToken = await getOrCreateDocAndToken(connectionString, searchParams.doc)

    return (
        <YDocProvider clientToken={clientToken} setQueryParam="doc">
            // Call your collaborative interface here
        </YDocProvider>
    )
}
```

--------------------------------

### Use useAwareness for presence

Source: https://github.com/jamsocket/y-sweet/blob/main/js-pkg/react/README.md

Retrieve an awareness object to enable presence features in editor bindings.

```tsx
const awareness = useAwareness()

bindingRef.current = new CodemirrorBinding(yText!, editorRef.current, awareness)
```

--------------------------------

### POST /d/{docId}/update

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Updates a document by applying a Yjs update binary.

```APIDOC
## POST /d/{docId}/update

### Description
Updates a document by applying a Yjs update. The request body should be the binary Yjs update data.

### Method
POST

### Endpoint
/d/{docId}/update

### Parameters
#### Path Parameters
- **docId** (string) - Required - The unique identifier for the document.

#### Request Body
- **binary** (blob) - Required - The binary Yjs update data.
```

--------------------------------

### useText Hook for Collaborative Text Editing

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Utilize the useText hook for real-time collaborative text editing. It provides methods to insert, delete, and retrieve text content. For advanced text editing features, consider integrating with bindings like y-codemirror.

```tsx
import { useText, useYDoc } from '@y-sweet/react'

function TextEditor() {
  // Get shared Y.Text for collaborative text editing
  const text = useText('document')

  // Access the raw Y.Doc if needed
  const doc = useYDoc()

  return (
    <textarea
      value={text.toString()}
      onChange={(e) => {
        // For basic text, though usually you'd use a binding like y-codemirror
        text.delete(0, text.length)
        text.insert(0, e.target.value)
      }}
    />
  )
}
```

--------------------------------

### Update Document with Yjs Update

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Update a document by sending a Yjs update binary payload. This operation requires full authorization and the Content-Type must be set to application/octet-stream.

```bash
# Update document with Yjs update binary
curl -X POST http://localhost:8080/d/my-document-id/update \
  -H "Authorization: Bearer <client-token>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @update.bin
```

--------------------------------

### DocumentManager Class

Source: https://context7.com/jamsocket/y-sweet/llms.txt

The DocumentManager class offers server-side operations for managing Yjs documents, such as creation, token generation, and content read/write.

```APIDOC
## DocumentManager Class

### Description
Provides server-side document management operations, including creating documents, generating client tokens, and reading/writing document content.

### Methods

#### `createDoc()`
Creates a new document.

- **Endpoint**: (Implicit, server-side)
- **Request Body**: None
- **Response**: Object containing `docId`.

#### `createDoc(docId: string)`
Creates a new document with a specific ID.

- **Endpoint**: (Implicit, server-side)
- **Parameters**:
  - **docId** (string) - Required - The desired ID for the document.
- **Request Body**: None
- **Response**: Object containing `docId`.

#### `getClientToken(docId: string, options?: { authorization?: 'read-only' | 'read-write'; validForSeconds?: number })`
Generates a client token for a given document.

- **Endpoint**: (Implicit, server-side)
- **Parameters**:
  - **docId** (string) - Required - The ID of the document.
  - **options** (object) - Optional - Authorization options.
    - **authorization** (string) - Optional - 'read-only' or 'read-write'.
    - **validForSeconds** (number) - Optional - Duration for which the token is valid.
- **Response**: Object containing `url`, `baseUrl`, `docId`, and `token`.

#### `getOrCreateDocAndToken(docId?: string)`
Gets an existing document or creates a new one, and generates a client token.

- **Endpoint**: (Implicit, server-side)
- **Parameters**:
  - **docId** (string) - Optional - The ID of the document to get or create.
- **Response**: Object containing `url`, `baseUrl`, `docId`, and `token`.

#### `getDocAsUpdate(docId: string)`
Retrieves a document's content as a Yjs update.

- **Endpoint**: (Implicit, server-side)
- **Parameters**:
  - **docId** (string) - Required - The ID of the document.
- **Response**: Yjs update (Uint8Array).

#### `updateDoc(docId: string, update: Uint8Array)`
Updates a document with a Yjs update.

- **Endpoint**: (Implicit, server-side)
- **Parameters**:
  - **docId** (string) - Required - The ID of the document.
  - **update** (Uint8Array) - Required - The Yjs update data.
- **Response**: None.

#### `createDocWithContent(update: Uint8Array)`
Creates a new document with initial content provided as a Yjs update.

- **Endpoint**: (Implicit, server-side)
- **Parameters**:
  - **update** (Uint8Array) - Required - The initial Yjs update data.
- **Response**: Object containing `docId`.

#### `checkStore()`
Checks the health of the storage.

- **Endpoint**: (Implicit, server-side)
- **Response**: Object with `ok` (boolean) and `error` (string, if not ok).

```

--------------------------------

### useMap Hook for Shared Y.Map Data

Source: https://context7.com/jamsocket/y-sweet/llms.txt

Access and manipulate shared Y.Map data structures. Changes made via the hook's methods automatically synchronize across clients. Use the 'observe' option to control re-render behavior ('deep', 'shallow', or 'none').

```tsx
import { useMap, useYDoc } from '@y-sweet/react'
import * as Y from 'yjs'

function ColorGrid() {
  // Get a shared Y.Map - all clients with same name share the same data
  const colors = useMap<string>('colorgrid')

  const handleClick = (x: number, y: number, color: string) => {
    colors.set(`${x},${y}`, color)
  }

  const clearCell = (x: number, y: number) => {
    colors.delete(`${x},${y}`)
  }

  return (
    <div>
      {Array.from({ length: 10 }, (_, i) => (
        <div key={i}>
          {Array.from({ length: 10 }, (_, j) => (
            <div
              key={j}
              style={{ backgroundColor: colors.get(`${i},${j}`) || 'white' }}
              onClick={() => handleClick(i, j, '#ff0000')}
            />
          ))}
        </div>
      ))}
    </div>
  )
}

// Control observation behavior
function OptimizedComponent() {
  // 'deep' (default) - re-render on any nested change
  // 'shallow' - re-render only on direct changes
  // 'none' - never re-render automatically
  const data = useMap('data', { observe: 'shallow' })
  return <div>{data.get('value')}</div>
}
```

--------------------------------

### Use useArray for shared lists

Source: https://github.com/jamsocket/y-sweet/blob/main/js-pkg/react/README.md

Access a Yjs Y.Array to maintain ordered lists of items, such as a To Do list.

```tsx
const items = useArray<Y.Map<any>>('todolist')

const pushItem = useCallback((text: string) => {
    let item = new Y.Map([
        ['text', text],
        ['done', false],
    ] as [string, any][])

    items?.push([item])
},[items])

const clearCompleted = useCallback(() => {
    let indexOffset = 0
    items?.forEach((item, index) => {
        if (item.get('done')) {
            items.delete(index - indexOffset, 1)
            indexOffset += 1
        }
    })
}, [items])
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.