You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A lightweight TypeScript/JavaScript SDK for Short.io's URL shortening API, designed specifically for browser environments with public key authentication.
4
-
5
-
## Features
6
-
7
-
- 🌐 **Browser-first**: Optimized for client-side applications
8
-
- 🔑 **Public Key Auth**: Works with Short.io public API keys
9
-
- 📦 **Lightweight**: Minimal dependencies, small bundle size
10
-
- 🎯 **TypeScript**: Full type safety with TypeScript support
11
-
- 🚀 **Modern**: Uses fetch API and ES modules
3
+
A lightweight TypeScript/JavaScript SDK for [Short.io](https://short.io)'s URL shortening API, designed for browser environments with public key authentication. Zero runtime dependencies.
|`originalURL`|`string`| Yes | The URL to shorten |
54
+
|`path`|`string`| No | Custom path for the short link |
55
+
|`title`|`string`| No | Link title |
56
+
|`tags`|`string[]`| No | Tags for organization |
57
+
|`folderId`|`string`| No | Folder ID |
58
+
|`cloaking`|`boolean`| No | Enable link cloaking |
59
+
|`password`|`string`| No | Password-protect the link |
60
+
|`passwordContact`|`boolean`| No | Require contact info with password |
61
+
|`redirectType`|`301 \| 302 \| 307 \| 308`| No | HTTP redirect status code |
62
+
|`utmSource`|`string`| No | UTM source parameter |
63
+
|`utmMedium`|`string`| No | UTM medium parameter |
64
+
|`utmCampaign`|`string`| No | UTM campaign parameter |
65
+
|`utmContent`|`string`| No | UTM content parameter |
66
+
|`utmTerm`|`string`| No | UTM term parameter |
67
+
|`androidURL`|`string`| No | Redirect URL for Android devices |
68
+
|`iphoneURL`|`string`| No | Redirect URL for iPhones |
69
+
|`clicksLimit`|`number`| No | Maximum number of clicks allowed |
70
+
|`skipQS`|`boolean`| No | Skip query string forwarding |
71
+
|`archived`|`boolean`| No | Create link as archived |
72
+
|`splitURL`|`string`| No | A/B test destination URL |
73
+
|`splitPercent`|`number`| No | A/B test traffic split percentage |
74
+
|`integrationAdroll`|`string`| No | AdRoll integration pixel |
75
+
|`integrationFB`|`string`| No | Facebook integration pixel |
76
+
|`integrationGA`|`string`| No | Google Analytics integration |
77
+
|`integrationGTM`|`string`| No | Google Tag Manager integration |
78
+
79
+
Returns `Promise<CreateLinkResponse>` with the full link object including `shortURL`, `secureShortURL`, `id`, and all configured properties.
69
80
70
81
### `client.expandLink(request)`
71
82
72
83
Expands a short link to get its details.
73
84
74
-
**Parameters:**
75
-
-`request.domain` (string): The Short.io domain
76
-
-`request.path` (string): The path of the short link
85
+
| Parameter | Type | Required | Description |
86
+
|-----------|------|----------|-------------|
87
+
|`domain`|`string`| Yes | The Short.io domain |
88
+
|`path`|`string`| Yes | The path of the short link |
89
+
90
+
Returns `Promise<ExpandLinkResponse>` (same shape as `CreateLinkResponse`).
77
91
78
-
**Returns:** Promise<ExpandLinkResponse>
92
+
### `client.createEncryptedLink(request)`
79
93
80
-
## Usage Examples
94
+
Creates an encrypted short link using AES-GCM encryption. The original URL is encrypted client-side before being sent to the API; the decryption key is placed in the URL fragment (hash) and never sent to the server.
81
95
82
-
### Basic Link Creation
96
+
Takes the same parameters as `createLink`. Returns `Promise<CreateLinkResponse>` where `shortURL` includes the `#key` fragment for decryption.
Tracks a conversion event using `navigator.sendBeacon()`. Reads the `clid` (click ID) query parameter from the current page URL to attribute the conversion.
109
+
110
+
| Parameter | Type | Required | Description |
111
+
|-----------|------|----------|-------------|
112
+
|`domain`|`string`| Yes | Your Short.io domain |
113
+
|`conversionId`|`string`| No | Custom conversion identifier |
114
+
|`value`|`number`| No | Monetary or numeric value for the conversion |
115
+
116
+
Returns `ConversionTrackingResult`:
93
117
94
118
```typescript
95
-
const link =awaitclient.createLink({
96
-
originalURL: 'https://docs.short.io',
97
-
domain: 'your-domain.com',
98
-
path: 'docs'
99
-
});
119
+
{
120
+
success: boolean; // true if clid was found and beacon sent
121
+
conversionId?:string;
122
+
clid?:string;
123
+
domain: string;
124
+
value?:number;
125
+
}
100
126
```
101
127
102
-
### With Tags
103
-
104
128
```typescript
105
-
const link =awaitclient.createLink({
106
-
originalURL: 'https://example.com',
129
+
const result =client.trackConversion({
107
130
domain: 'your-domain.com',
108
-
tags: ['marketing', 'campaign-2024']
131
+
conversionId: 'purchase',
132
+
value: 49.99
109
133
});
134
+
135
+
if (result.success) {
136
+
console.log('Conversion tracked for click:', result.clid);
137
+
}
110
138
```
111
139
112
-
### Error Handling
140
+
### `client.getClickId()`
141
+
142
+
Returns the `clid` query parameter from the current page URL, or `null` if not present.
113
143
114
144
```typescript
115
-
try {
116
-
const link =awaitclient.createLink({
117
-
originalURL: 'https://example.com',
118
-
domain: 'your-domain.com'
119
-
});
120
-
} catch (error) {
121
-
console.error('Failed to create link:', error.message);
122
-
}
145
+
const clickId =client.getClickId();
123
146
```
124
147
125
-
##Browser Support
148
+
### `client.observeConversions(options)`
126
149
127
-
This SDK works in all modern browsers that support:
128
-
- Fetch API
129
-
- ES2018 features
130
-
- Promises/async-await
150
+
Enables declarative conversion tracking via HTML `data-` attributes. Scans the DOM for elements with `data-shortio-conversion` and automatically binds event listeners. Also watches for dynamically added elements using a `MutationObserver`.
131
151
132
-
For older browsers, you may need polyfills for the fetch API.
152
+
| Parameter | Type | Required | Description |
153
+
|-----------|------|----------|-------------|
154
+
|`domain`|`string`| Yes | Your Short.io domain |
133
155
134
-
## Bundle Formats
156
+
Returns a `ConversionObserver` with a `disconnect()` method to remove all listeners and stop observing.
135
157
136
-
The SDK is available in multiple formats:
158
+
**HTML attributes:**
137
159
138
-
-**ES Modules**: `dist/index.esm.js` (recommended for modern bundlers)
@@ -150,33 +203,56 @@ The SDK is available in multiple formats:
150
203
</script>
151
204
```
152
205
153
-
## Getting Your API Key
206
+
## TypeScript
154
207
155
-
1. Visit your [Short.io dashboard](https://app.short.io)
156
-
2. Go to Integrations & API
157
-
3. Create a new public API key for your domain
208
+
Full type definitions are included. All types are exported:
158
209
159
-
⚠️ **Security Note**: Public keys are safe to use in browser environments but have limited permissions. Never use private API keys in client-side code.
210
+
```typescript
211
+
importtype {
212
+
ShortioConfig,
213
+
CreateLinkRequest,
214
+
CreateLinkResponse,
215
+
ExpandLinkRequest,
216
+
ExpandLinkResponse,
217
+
ConversionTrackingOptions,
218
+
ConversionTrackingResult,
219
+
ObserveConversionsOptions,
220
+
ConversionObserver,
221
+
ApiError
222
+
} from'@short.io/client-browser';
223
+
```
160
224
161
-
## TypeScript Support
225
+
## Error Handling
162
226
163
-
The SDK includes full TypeScript definitions. All methods and responses are fully typed:
227
+
API errors throw a standard `Error` with the message from the Short.io API response:
0 commit comments