Quick start

# Clone and install
git clone https://github.com/itayshmool/commently.git
cd commently
npm install

# Create the database
createdb commently

# Configure
cp .env.example .env
# Edit .env — set DATABASE_URL and ADMIN_API_KEY

# Run migrations and start
npm run db:migrate
npm run dev
# → Commently listening on port 3002

curl -X POST http://localhost:3002/api/tenants \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app"}'

# → {"success":true,"data":{"id":"...","name":"my-app","api_key":"sk_commently_..."}}
# Save the api_key — it's shown only once.

X-API-Key: sk_commently_abc123def456...

Authorization: Bearer your-admin-key

{
  "success": true,
  "data": { ... }
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Comment not found"
  }
}

curl -X POST http://localhost:3002/api/tenants \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "deckdrop"}'

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-...",
    "name": "deckdrop",
    "api_key": "sk_commently_abc123..."
  }
}

curl http://localhost:3002/api/tenants \
  -H "Authorization: Bearer $ADMIN_KEY"

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-...",
      "name": "deckdrop",
      "api_key_prefix": "sk_commently_abc1...",
      "created_at": "2026-06-01T10:00:00Z"
    }
  ]
}

curl -X POST http://localhost:3002/api/tenants/$TENANT_ID/rotate-key \
  -H "Authorization: Bearer $ADMIN_KEY"

{
  "success": true,
  "data": {
    "api_key": "sk_commently_newkey..."
  }
}

curl -X DELETE "http://localhost:3002/api/tenants/$TENANT_ID" \
  -H "Authorization: Bearer $ADMIN_KEY"

{
  "success": true,
  "data": { "id": "a1b2c3d4-...", "deleted": true }
}

curl -X POST http://localhost:3002/api/comments \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_id": "deck-uuid-123",
    "context_key": "slide:3",
    "author_id": "viewer@gmail.com",
    "author_name": "Dana",
    "author_role": "viewer",
    "body": "Love this chart!"
  }'

{
  "success": true,
  "data": {
    "id": "c9a2f1b3-...",
    "resource_id": "deck-uuid-123",
    "context_key": "slide:3",
    "author_id": "viewer@gmail.com",
    "author_name": "Dana",
    "author_role": "viewer",
    "body": "Love this chart!",
    "parent_id": null,
    "created_at": "2026-06-05T10:30:00Z"
  }
}

curl "http://localhost:3002/api/comments?resource_id=deck-uuid-123&context_key=slide:3" \
  -H "X-API-Key: $API_KEY"

{
  "success": true,
  "data": {
    "comments": [
      {
        "id": "c9a2f1b3-...",
        "resource_id": "deck-uuid-123",
        "context_key": "slide:3",
        "author_id": "viewer@gmail.com",
        "author_name": "Dana",
        "author_role": "viewer",
        "body": "Love this chart!",
        "parent_id": null,
        "created_at": "2026-06-05T10:30:00Z",
        "replies": [
          {
            "id": "d4e5f6a7-...",
            "author_id": "itay@wix.com",
            "author_name": "Itay",
            "author_role": "owner",
            "body": "Thanks! Data is from Q3 report",
            "parent_id": "c9a2f1b3-...",
            "created_at": "2026-06-05T10:32:00Z"
          }
        ]
      }
    ],
    "pagination": {
      "next_cursor": "c9a2f1b3-...",
      "has_more": false
    }
  }
}

curl "http://localhost:3002/api/comments/counts?resource_id=deck-uuid-123&group_by=context_key" \
  -H "X-API-Key: $API_KEY"

{
  "success": true,
  "data": {
    "total": 8,
    "groups": {
      "slide:0": 2,
      "slide:3": 5,
      "slide:7": 1
    }
  }
}

curl "http://localhost:3002/api/comments/counts?resource_ids=deck-1,deck-2,deck-3" \
  -H "X-API-Key: $API_KEY"

{
  "success": true,
  "data": {
    "counts": {
      "deck-1": 8,
      "deck-2": 3,
      "deck-3": 0
    }
  }
}

curl -X DELETE "http://localhost:3002/api/comments/$COMMENT_ID" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Author-Id: admin@example.com"

{
  "success": true,
  "data": {
    "id": "c9a2f1b3-...",
    "deleted_at": "2026-06-05T11:00:00Z",
    "deleted_by": "admin@example.com"
  }
}

curl -X PATCH "http://localhost:3002/api/comments/$COMMENT_ID" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"author_id": "viewer@gmail.com", "body": "Updated comment text"}'

{
  "success": true,
  "data": {
    "id": "c9a2f1b3-...",
    "body": "Updated comment text",
    "edited_at": "2026-06-05T10:35:00Z"
  }
}

curl -X POST "http://localhost:3002/api/comments/$COMMENT_ID/reactions" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"author_id": "user@example.com", "emoji": "👍"}'

{
  "success": true,
  "data": {
    "id": "r1a2b3c4-...",
    "comment_id": "c9a2f1b3-...",
    "author_id": "user@example.com",
    "emoji": "👍"
  }
}

{
  "success": true,
  "data": [
    { "emoji": "👍", "count": 3, "authors": ["alice@ex.com", "bob@ex.com", "carol@ex.com"] },
    { "emoji": "❤️", "count": 1, "authors": ["alice@ex.com"] }
  ]
}

curl -X DELETE "http://localhost:3002/api/comments/$COMMENT_ID/reactions" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"author_id": "user@example.com", "emoji": "👍"}'

curl -X POST http://localhost:3002/api/webhooks \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://myapp.com/webhook", "secret": "my-signing-secret"}'

{
  "event": "comment.created",
  "data": { "id": "...", "body": "...", ... },
  "timestamp": "2026-06-05T10:30:00.000Z"
}

{
  "success": true,
  "data": {
    "resource_id": "deck-uuid-123",
    "count": 42,
    "comments": [ ... ]
  }
}

curl "http://localhost:3002/api/export/tenant/$TENANT_ID" \
  -H "Authorization: Bearer $ADMIN_KEY"

const COMMENTLY_URL = process.env.COMMENTLY_URL || 'http://localhost:3002';
const COMMENTLY_KEY = process.env.COMMENTLY_API_KEY;

async function commently(method, path, body) {
  const res = await fetch(`${COMMENTLY_URL}${path}`, {
    method,
    headers: {
      'X-API-Key': COMMENTLY_KEY,
      'Content-Type': 'application/json',
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  return res.json();
}

// In your app's comment handler — after verifying the user is authenticated
app.post('/api/my-app/comments', async (req, res) => {
  const user = req.user; // your auth
  const { resourceId, contextKey, body } = req.body;

  const result = await commently('POST', '/api/comments', {
    resource_id: resourceId,
    context_key: contextKey,
    author_id: user.email,
    author_name: user.displayName,
    author_role: user.role, // "owner", "viewer", etc.
    body,
  });

  res.json(result);
});

app.get('/api/my-app/comments', async (req, res) => {
  const { resourceId, contextKey, cursor } = req.query;

  const params = new URLSearchParams({ resource_id: resourceId });
  if (contextKey) params.set('context_key', contextKey);
  if (cursor) params.set('cursor', cursor);

  const result = await commently('GET', `/api/comments?${params}`);
  res.json(result);
});

// Get counts per slide for a deck
const counts = await commently(
  'GET',
  `/api/comments/counts?resource_id=${deckId}&group_by=context_key`
);

// counts.data.groups → { "slide:0": 2, "slide:3": 5 }
// Use these to render badges on each slide thumbnail

// Batch mode — get total counts for a list of decks
const batch = await commently(
  'GET',
  `/api/comments/counts?resource_ids=${deckIds.join(',')}`
);
// batch.data.counts → { "deck-1": 8, "deck-2": 3 }

// Create a reply
await commently('POST', '/api/comments', {
  resource_id: 'deck-uuid-123',
  context_key: 'slide:3',
  author_id: 'bob@example.com',
  author_name: 'Bob',
  body: 'Agreed!',
  parent_id: 'c9a2f1b3-...', // ID of the parent comment
});