Using the SDK

The zero-config Gigadrive client inside a deployed Function, and how to get working credentials in local development.

Inside a deployed Function, new GigadriveClient() takes no arguments: the SDK finds the injected credentials in the environment and exchanges them for a token on the first call. On your own machine that environment does not exist, so you provision a development key with the CLI.

Calling the API from a Function

This handler mints a signed URL for a private storage object and returns it to the browser. It needs network:storage_objects:read, which a Function already has.

// app/api/report-url/route.ts
import { GigadriveClient } from '@gigadrive/sdk';

// Credentials, application context, and API host all come from the injected environment.
const client = new GigadriveClient();

export async function GET(request: Request) {
  const objectId = new URL(request.url).searchParams.get('id');

  if (!objectId) {
    return Response.json({ error: 'Missing id' }, { status: 400 });
  }

  const { url, expiresAt } = await client.storage.objects.getAccessUrl('reports', objectId, {
    expiresInSeconds: 900,
  });

  return Response.json({ url, expiresAt });
}

Without the SDK it is two calls: exchange the injected pair for a token at /oauth2/token, then send that token on the resource request.

Two things the client does that the shell version does not. It keeps the token and refreshes it 30 seconds before expiry, sharing one refresh between concurrent calls rather than stampeding the token endpoint. And on a 401 it invalidates the token, fetches a new one, and replays the request exactly once before giving up with an AuthenticationError.

The bucket is addressed by name, reports, and no environment is passed. A Function's credential already names its deployment, so the API resolves the bucket in the right environment on its own.

Which credential the client picks

Resolution stops at the first match:

bearerToken, then clientId with clientSecret, then refreshToken with clientId, passed to the constructor.
GIGADRIVE_BEARER_TOKEN from the environment.
GIGADRIVE_CLIENT_ID with GIGADRIVE_CLIENT_SECRET from the environment, which is the injected pair.

With none of those present the constructor throws AuthenticationError immediately, before any request is made. That is the error you get when you run the same code on a laptop with an empty .env.local.

Local development

From the project directory, with the application linked by gigadrive link, pull its variables together with a development credential:

gigadrive env pull --with-credentials

The command writes your application's non-sensitive variables into .env.local, appends GIGADRIVE_CLIENT_ID, GIGADRIVE_CLIENT_SECRET and GIGADRIVE_API_BASE_URL, and adds .env.local to .gitignore if it is not already listed. Sensitive values are never pulled, and the command prints how many it skipped.

A development key is narrower than a Function's

The key the CLI mints is application-scoped and carries one scope, network:env_vars:read. Calls a deployed Function is allowed to make, such as creating an upload session, come back as 403 with an insufficient-scope error when you run them locally. Create a key with the scopes you need as described in API keys, then put its id and secret in .env.local under the same two variable names.

The key is named after your machine and the application, it is reused on later pulls, and it expires after 90 days.

To replace it, for example after a laptop goes missing, run gigadrive env pull --with-credentials --rotate, which revokes the old key before minting the new one.