@canvasync/contracts

Shared Protocol Buffer contracts for CanvaSync - real-time collaborative whiteboard.

Overview

This package contains:

• Protocol Buffer definitions (.proto files)
• Generated TypeScript types (npm package)
• Generated C# classes (for .NET API)

Changelog

Release history is tracked in CHANGELOG.md.

Installation

TypeScript/JavaScript (Frontend)

# Option 1: pnpm link (recommended for local dev)
cd canvasync-contracts && pnpm link --global
cd ../canvasync-web && pnpm link --global @canvasync/contracts

# Option 2: npm install (after publishing)
pnpm add @canvasync/contracts

C# (.NET API)

Copy generated files from generated/dotnet/ to your project and add:

dotnet add package Google.Protobuf

📖 For detailed consumption options, see docs/CONSUMING.md

Usage

TypeScript

import {
  ClientMessage,
  ServerMessage,
  StrokePoint,
  JoinBoard,
} from "@canvasync/contracts";

// Create a message
const joinMsg: ClientMessage = {
  joinBoard: {
    boardId: "board-123",
    userId: "user-456",
    userName: "John",
    color: "#FF5733",
  },
};

// Encode for WebSocket
const encoded = ClientMessage.encode(joinMsg).finish();
websocket.send(encoded);

// Decode incoming message
const decoded = ServerMessage.decode(new Uint8Array(data));
if (decoded.boardState) {
  console.log("Board state received:", decoded.boardState);
}

C#

using CanvaSync.Contracts.Realtime;
using Google.Protobuf;

// Create a message
var msg = new ServerMessage
{
    BoardState = new BoardState
    {
        BoardId = "board-123",
        BoardName = "My Whiteboard"
    }
};

// Serialize
byte[] bytes = msg.ToByteArray();

// Deserialize
var received = ClientMessage.Parser.ParseFrom(bytes);
if (received.PayloadCase == ClientMessage.PayloadOneofCase.JoinBoard)
{
    var join = received.JoinBoard;
    Console.WriteLine($"User {join.UserName} joined");
}

Development

Prerequisites

• Node.js 22+
• pnpm
• protoc (Protocol Buffers compiler)

# macOS
brew install protobuf

# Verify
protoc --version

Generate Contracts

# Install dependencies
pnpm install

# Generate TypeScript & C# from proto files
pnpm generate

# Build TypeScript package
pnpm build

Project Structure

canvasync-contracts/
├── proto/                    # Source .proto files
│   ├── realtime.proto        # WebSocket message types
│   └── events.proto          # Kafka event types
├── generated/
│   ├── typescript/           # Generated TS (gitignored)
│   └── dotnet/               # Generated C# (gitignored)
├── dotnet/
│   └── CanvaSync.Contracts/  # .NET NuGet package project
├── src/
│   └── index.ts              # Package entry point
├── scripts/
│   ├── generate.sh           # Code generation script
│   └── sync-versions.sh      # Version sync script
├── docs/
│   ├── CONSUMING.md          # How to use in projects
│   └── PUBLISHING.md         # How to publish packages
└── package.json

Proto Files

realtime.proto

WebSocket binary protocol messages:

• ClientMessage - Messages from browser to server
• ServerMessage - Messages from server to browser
• Drawing types: StrokeStart, StrokePoint, StrokeEnd
• Presence types: CursorMove, UserJoined, UserLeft

events.proto

Kafka event types for persistence and analytics:

• BoardCreatedEvent, BoardDeletedEvent
• StrokeCreatedEvent, StrokeDeletedEvent
• UserJoinedBoardEvent, UserLeftBoardEvent
• BoardActivityEvent (analytics)

License

MIT