JavaScript library of public Surge API endpoints. Sharing structure and documentation in an open sourc environment.
- Common JS (CJS) enabled
- ES Modules (ESM) enabled
- TypeScript enabled
Using npm:
npm install surgejs-sdk
Using yarn:
yarn add surgejs-sdk
note: CommonJS usage
const Surge = require('surgejs-sdk');
Logging the user into surge servers
const Surge = require('surgejs-sdk');
const surge = new Surge({
username: 'email@domain.com',
password: 'password'
});
surge
.login()
.then(function(response) {
// handle success
console.log(response);
})
.catch(function(error) {
// handle error
console.log(error);
});
Every API must have Basic Authentication attached with user credentials. This is required for any call made to the servers.
When using the surgejs-sdk library, all you need to do is provide your credentials in the new Surge({username: 'email@domain.com', password: 'password})
arguments. No need to worry about http headers.
All provided methods are promise based so we won't add .then(...).catch(...)
to all of the examples.
Authenticate the user with surge servers using their email and password provided upon initiation of the library. See Installation
surge.login();
Response
{
"email": "email@domain.com",
"token": "abcdefg0123456789"
}
Logout is an informal event. Remove your locally stored credentials (email, token) to "logout" the user.
Get the user's account information.
surge.account();
Response
{
"email": "email@domain.com",
"id": "0000-0000-0000",
"uuid": "00000000-0000-0000-0000-000000000000",
"role": 0,
"updated_at": "2020-01-01T01:01:01.000Z",
"created_at": "2020-01-01T01:01:01.000Z",
"email_verified_at": "2020-01-01T01:01:01.000Z",
"payment_id": null,
"plan": {
"id": "abcdefg-00",
"name": "abcdefg",
"amount": "0000",
"friendly": "abcdefg",
"dummy": true,
"current": true,
"metadata": {
"type": "account"
},
"ext": "00",
"perks": [],
"comped": false
},
"card": null
}
Initiate password reset steps for a user's email.
surge.resetPassword('email@domain.com');
Response
Reset instructions send to email.
Get stats about your account usage.
surge.stats();
Response
{
"calls": "7515855",
"deployemnts": "7515855",
"bytes": "77879308777468",
"files": "903079863",
"accounts": "148665",
"projects": "1193327",
"builds": "1169",
"deployments": "7515855",
"formatted": {
"calls": "7,515,855",
"deployments": "7,515,855",
"bytes": "70.83 TB",
"files": "903,079,863",
"accounts": "148,665",
"projects": "1,193,327",
"builds": "1,169"
}
}
Surge Cli uses moniker to randomly generate domain name for the user.
surge.discover();
surge.list();
Response
[
{
"domain": "domain_name.surge.sh",
"planName": "Standard",
"output": {},
"rev": 0123456789,
"config": {},
"cmd": "surge",
"email": "email@domain.com",
"platform": "surge.sh",
"cliVersion": "0.21.7",
"message": null,
"buildTime": null,
"ip": "00.000.000.00",
"privateFileList": [],
"publicFileCount": 00,
"publicTotalSize": 000000,
"privateFileCount": 00,
"privateTotalSize": 0000000,
"uploadStartTime": 0000000000000,
"uploadEndTime": 0000000000000,
"uploadDuration": 1.000,
"preview": "0000000000000-domain_name.surge.sh",
"timeAgoInWords": "4 weeks ago"
},
...
]
Not yet implemented.
PUT https://surge.surge.sh/<domain_name>
Content-Types: application/json
Parameters | Type | Default | Description |
---|---|---|---|
domain | string |
N/A |
domain_name .surge.sh which you would like to create. Do not include ".surge.sh". |
data | gzip |
N/A | Tar packed, gzip files including the index.html to serve your static site. |
Project is ran through three pipes in the cli:
// cli files:
// 1. prep.js
// 2. deploy.js
// 3. project.js
var fsReader = require('surge-fstream-ignore');
// Read Project
var project = fsReader({ path: req.project, ignoreFiles: ['.surgeignore'] });
// we always ignore .git directory
project.addIgnoreRules(ignore);
// chain all this together...
project
.pipe(tar.Pack())
.pipe(zlib.Gzip())
.pipe(handshake);
Untested libraries equivalent to Node:
Remove the domain and hosted site from surge servers. e.g. domain_name.surge.sh
.
surge.teardown('domain_name');
Response
{
"msg": "project removed",
"nsDomain": "surge.world",
"regions": {},
"servers": []
}
Payments are still under development.
N/A
N/A
Multi step process.
- If the user does not exist in stripe, choose a plan and credit card information.
- If the user exists in stripe, choose a new plan to pay for.
+++ Request
GET https://surge.surge.sh/<domain_name>/plans
Content-Types: application/json
Response
N / A
N/A
Requires an undocumented Stripe call to get user's Stripe data.
PUT https://surge.surge.sh/<domain_name>/plan
Content-Types: application/json
Body
Parameter | Type | Default | Description |
---|---|---|---|
token | string |
N/A | Payment Token |
Response
N / A
GET https://surge.surge.sh/<domain_name>/subscription
Content-Types: application/json
Response
{
"type": "",
"stripe_pk": "",
"plan": {},
"card": null,
"perks": []
}
Technical support questions are best asked in the Discussions. We will do our best to assist as soon as possible.
If you find a defect or would like to submit a feature request, please create an Issue and we will investigate right away.