U301 plugin

<api key>
<workspace id>

• A new link spends one slot of the monthly allowance, and free accounts get 100 a month. Reusing a link does not: pass reuseExisting to return the existing link for a URL instead of making a second one, and check isReused on the answer. An exhausted allowance answers 429 with the MONTHLY_LINK_LIMIT_REACHED code, which is never retried; a bare 429 is a throughput limit, and only replayable calls are retried after Retry-After.
• A link looks different on create than on read. A create answers shortLink, url and isReused; a read answers shortUrl, originalUrl and statsClicks. The two shapes are modelled as they are rather than merged.
• Links and domains are addressed by their own name, not an internal id. links.get takes the short form, u301.co/abc123, and it is sent as a path with its slash rather than an encoded %2F. A https:// prefix is stripped for you.
• A custom domain is not live when it is created. domains.create adds it, then you create the CNAME from dnsSettings.cnameValue and poll domains.active until actived is true — that is U301’s own spelling of the field. A domain that is still verifying answers actived: false with a message such as “Challenge not ready”.
• The three domain settings share one PATCH but are separate operations, so each sends exactly one field: domains.pathLength (randomCodeLength, 3 to 10), domains.homeRedirect and domains.notFoundRedirect. The two redirects are Pro plan features: a free workspace gets 403 “This feature is only available for Pro Plan”.
• Analytics separate range from granularity. range is how far back (24h, 1d, 3d, 7d, 14d, 30d, 60d, 1m) and granularity is how the buckets are cut (day, hour). Give timezone when the day boundary matters.
• The audience breakdown puts the dimension in the path. analytics.audience takes countries, cities, referers, browsers, operating-systems or device-types and calls the matching top-<dimension> route. Three of those are the provider’s own spellings, so they are not the words you might guess.

• 14 typed API operations

​

Setup

npm install corsair @corsair-dev/u301 better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/u301 better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/u301 better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/u301 better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { u301 } from '@corsair-dev/u301';

export const corsair = createCorsair({
	plugins: [
		u301(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

u301()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'u301',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

​

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.u301.api.links.list({ page: 1, perPage: 20 });

const tenant = corsair.withTenant('acme');
await tenant.u301.api.links.create({
	url: 'https://example.com/spring-sale',
	domain: 'go.example.com',
	slug: 'spring',
	reuseExisting: true,
});

​

What’s next