michaelmcshinsky/surgejs-sdk

API library for Surge.sh public endpoints

SurgeJS SDK

JavaScript library of public Surge API endpoints. Sharing structure and documentation in an open source environment.

Table of Contents

• Features
• Installation
• Example
• Methods
  • Authentication
  • Projects
  • Payments
• Support

Features

• Common JS (CJS) enabled
• ES Modules (ESM) enabled
• TypeScript enabled

Installation

Using npm:

npm install surgejs-sdk

Using yarn:

yarn add surgejs-sdk

Example

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 protected]',
  password: 'password'
});

surge
  .login()
  .then(function(response) {
    // handle success
    console.log(response);
  })
  .catch(function(error) {
    // handle error
    console.log(error);
  });

API

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 protected]', password: 'password}) arguments. No need to worry about http headers.

Methods

All provided methods are promise based so we won't add .then(...).catch(...) to all of the examples.

Authentication

• Login
• Logout
• Account
• Reset Password
• Stats

Login

Authenticate the user with surge servers using their email and password provided upon initiation of the library. See Installation

surge.login();

Response

{
  "email": "[email protected]",
  "token": "abcdefg0123456789"
}

Logout

Logout is an informal event. Remove your locally stored credentials (email, token) to "logout" the user.

Account

Get the user's account information.

surge.account();

Response

{
  "email": "[email protected]",
  "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
}

Reset Password

Initiate password reset steps for a user's email.

surge.resetPassword('[email protected]');

Response

Reset instructions send to email.

Stats

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"
  }
}

Projects

• Discover
• List
• Deploy
• Teardown

Discover

Surge Cli uses moniker to randomly generate domain name for the user.

surge.discover();

List

surge.list();

Response

[
    {
    "domain": "domain_name.surge.sh",
    "planName": "Standard",
    "output": {},
    "rev": 0123456789,
    "config": {},
    "cmd": "surge",
    "email": "[email protected]",
    "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"
  },
  ...
]

Deploy

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:

• Tar - tar-js
• GZip - gzip-js

Teardown

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

• Card
• Set Card
• Payment
• Plans
• Subscribe
• Subscription

Payments are still under development.

Card

N/A

Set Card

N/A

Payment

Multi step process.

1. If the user does not exist in stripe, choose a plan and credit card information.
2. 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

Plans

N/A

Plus

Requires an undocumented Stripe call to get user's Stripe data.

Subscribe

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

Subscription

GET https://surge.surge.sh/<domain_name>/subscription
Content-Types: application/json

Response

{
  "type": "",
  "stripe_pk": "",
  "plan": {},
  "card": null,
  "perks": []
}

Support

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.