Build with the API

Live updates

Watch a report being built and a quota being used over one Socket.IO connection.

Open one connection and Gridline tells you what is happening as it happens: a report moving from queued to ready, a quota being spent, a notification arriving, a colleague typing a comment. Nothing to poll.

Connect

Gridline uses Socket.IO. Connect to the same address as the app and send your access token in the handshake:

import { io } from "socket.io-client";

const socket = io("https://gridline-data-analysis-app.duckdns.org", {
  auth: { token: accessToken },   // the access token from signing in
});

socket.on("file.status", ({ fileId, status, qualityScore }) => {
  console.log(fileId, status, qualityScore);
});

Use an access token (a session). API keys are for programs calling the REST API, and are refused here.
If the token is bad, the person is disabled, or their company is not active, the connection is refused with one generic "Unauthorized".
The server decides what you are allowed to hear. You send it nothing except the handshake and the few commands listed below.

What you hear

Event	Payload	Who hears it
`file.status`	`fileId`, `status`, `error`, `qualityScore`	Everyone who may see that file.
`quota.updated`	`plan`, `periodKey`, `filesUsed`, `filesLimit`	The company.
`notification.created`	The new notification, as `GET /notifications` returns it	Only its owner.
`audit.appended`	`id`, `action`, `actorUserId`, `targetType`, `targetId`, `createdAt`	Admins.
`comment.created`, `comment.updated`, `comment.deleted`	The comment	People watching that file.
`comment.typing`	`fileId`, `userId`, `isTyping`	People watching that file.
`presence.changed`	`fileId`, `userIds`	People watching that file.
`session.expiring`, `session.expired`	`expiresAt` / `expiredAt`	You.

Only after it is true

Events are sent after the change is saved, never during. If an upload is rolled back, nobody is told it happened. Who hears an event is worked out at the moment it is sent, from the file's current access: a restricted file's events reach only the people who may see it.

Watch a file

To follow one file's comments, who is looking, and who is typing, tell the server you are watching it:

JavaScript

socket.emit("file.watch", { fileId }, (result) => {
  // { ok: true }  or  { ok: false, error: "unauthorized" | "rate_limited" | "too_many_files" }
});

socket.emit("comment.typing", { fileId, isTyping: true });
socket.emit("file.unwatch", { fileId }, () => {});

You can watch up to 20 files at once per connection, and send up to 20 watch commands every 10 seconds.
Typing indicators are limited to 5 a second.
If a file's access changes and you may no longer see it, you are removed from its room immediately.

Stay connected

A connection lives as long as the access token it started with. About a minute before the end you receive session.expiring; at the end, session.expired, and the server disconnects. To carry on, get a new token and tell the server:

JavaScript

socket.on("session.expiring", async () => {
  const fresh = await refreshAccessToken();
  socket.emit("auth.refresh", { token: fresh }, (result) => {
    // { ok: true, expiresAt } or { ok: false, error: "unauthorized" }
  });
});