Security News
GitHub Removes Malicious Pull Requests Targeting Open Source Repositories
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
gearworks-http
Advanced tools
A standardized HTTP client used by Gearworks apps, backed by Axios. Gearworks is the best way to get started with building Shopify apps!
A standardized HTTP client used by Gearworks apps, backed by Axios. Gearworks is the best way to get started with building Shopify applications!
You can install this package from NPM with the NPM CLI or with Yarn (recommended):
# With NPM
npm install gearworks-http --save
# With Yarn
yarn add gearworks-http
You can import the BaseClient via require or TypeScript's import:
// Import with TypeScript or ES6
import BaseClient from "gearworks-http";
// Import via Node's require:
const BaseClient = require("gearworks-http").default;
This package provides a base, abstract client for you to extend with your own custom logic. When constructing your class, you need to make a call to the base client with super(baseUrl, defaultHeaders?, proxy?)
, passing along the baseUrl
and two other optional variables (documented below) for all requests made by your class.
import BaseClient from "gearworks-http";
export class MyClientClass extends BaseClient {
constructor() {
super("http://example.com/api", {
"X-Custom-Header-Name": "custom header value sent with each request"
})
}
public getFooObject(id: string) => this.sendRequest<FooType>(`foos/${id}`, "GET");
public listFooObjects(page: number = 1) => this.sendRequest<FooType>(`foos`, "GET", {
qs: {
page: page
}
});
public createFooObject(foo: FooType) => this.sendRequest<FooType>(`foos`, "POST", {
body: foo
});
public updateFooObject(id: string, foo: FooType) => this.sendRequest<FooType>(`foos/${id}`, "PUT", {
body: foo
});
public deleteFooObject(id: string) => this.sendRequest<void>(`foos/${id}`, "DELETE");
}
The this.sendRequest<T>
function returns a promise that can be awaited when using TypeScript or Babel, and will throw an ApiError
when the server responds with a status code that isn't OK.
The abstract BaseClient class should be extended by your own custom API client classes. When extending the BaseClient, you need to call super()
which accepts the following variables:
Variable | Type | Required | Description | Example |
---|---|---|---|---|
baseUrl | string | true | A base URL string (relative or absolute) that will be used for all requests made with this particular instance. | "http://localhost:3000" |
headers | object | false | An object containing headers, e.g. auth headers, that will be sent along with all requests. | { 'header-name': 'custom header value' } |
proxy | object | false | An Axios proxy config object that will be used for all requests. Useful for debugging requests with e.g. Fiddler | { host: "127.0.0.1", port: 8888} |
A protected function that your client class should use to make requests. When using TypeScript, this function accepts a type parameter that can be used to tell the compiler what return type you expect from your request.
Variable | Type | Required | Description | Example |
---|---|---|---|---|
path | string | true | The endpoint path you're making a request to. Will be combined with the baseUrl used in the constructor. | "foos/123" |
method | string | true | Method to use for the request. Accepted values are "POST" , "PUT" , "GET" , "DELETE" . | "POST" |
data | object | false | Object containing an optional body property with your POST or PUT object and an optional qs property with a querystring parameter object. | { body: { propName: "prop value" }, qs: { paramName: "param value" } } |
This function returns a Promise<T>
that can be awaited with TypeScript or Babel. The default implementation will deserialize the response body to an object (type T
when using TypeScript) and return it.
You can override this function with your own implementation:
import BaseClient, { RequestData, isOkay } from "gearworks-http";
export class MyClientClass extends BaseClient {
constructor() {
super("http://example.com/api", {
"X-Custom-Header-Name": "custom header value sent with each request"
})
}
// Override the sendRequest function
protected async sendRequest<T>(path: string, method: "POST" | "PUT" | "GET" | "DELETE", data: RequestData = { }) {
// Make your own custom request with this.Axios here.
const request = this.Axios.request({
...
})
let result: AxiosResponse;
let body: any;
try {
result = await request;
body = result.data;
} catch (e) {
// Axios was configured to only throw an error when a network error is encountered, not when the server returns a not-OK response.
}
if (!isOkay) {
const error = this.parseErrorResponse(body, result);
throw error;
}
const output: T = ...
return output;
}
}
A protected function that the client class uses to parse error responses. You shouldn't need to call this function directly unless you're using a custom version of BaseClient.sendRequest<T>
. When this function is called, it must return an ApiError
– the caller already knows there was an error, it just wants this function to parse it.
The default implementation of this function is configured to parse errors returned by the Gearworks API:
{
"message": "Something crazy happened",
"details": [
{
"key": "foo",
"details": [
"here's an itemized list of everything wrong with this prop",
"1. ...",
"2. ..."
]
}
]
}
Variable | Type | Required | Description | Example |
---|---|---|---|---|
body | string | false | The response body object or raw string. This may be null! | { message: "Something crazy happened", ... } |
axiosResponse | AxiosResponse | false | The Axios response itself, containing the status code and status text. This may be null! | {status: 500, statusText: "Internal server error", ...} |
You can override this function with your own implementation, which is particularly useful when you're making requests to a server that isn't using Gearworks:
import BaseClient, { ApiError } from "gearworks-http";
export class MyClientClass extends BaseClient {
constructor() {
super("http://example.com/api", {
"X-Custom-Header-Name": "custom header value sent with each request"
})
}
protected parseErrorResponse(body?: string | Object, axiosResponse?: AxiosResponse) {
const statusCode = 66;
const statusText = "I AM THE SENATE.";
const message = "It's treason then.";
const details = {
"sheev": "Are you threatening me, Master Jedi?"
}
const error = new ApiError(66, "I AM THE SENATE", "It's treason then.");
error.details = details;
return error;
}
}
The ApiError
is a custom Error class that's returned by the BaseClient.parseErrorResponse
function and thrown by the default implementation of BaseClient.sendRequest<T>
function. It has the following properties:
Variable | Type | Description | Example |
---|---|---|---|
status_code | number | The response status code. | 500 |
status_text | string | The status text corresponding with the status_code . | "Internal Server Error" . |
unauthorized | boolean | Indicates whether the response is a 401 unauthorized response. Automatically set in the ApiError class constructor. | false |
message | string | A message describing the error. | "It's treason then." |
details | any | A property set by the BaseClient.parseErrorResponse function that describes extra error details. May be null or undefined. | {"sheev": "Are you threatening me, Master Jedi?"} |
FAQs
A standardized HTTP client used by Gearworks apps, backed by Axios. Gearworks is the best way to get started with building Shopify apps!
The npm package gearworks-http receives a total of 1 weekly downloads. As such, gearworks-http popularity was classified as not popular.
We found that gearworks-http demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.