@foxy.io/sdk
Version:
Universal SDK for a full server-side and a limited in-browser access to Foxy hAPI.
260 lines (259 loc) • 9.02 kB
TypeScript
import { JSDOM } from 'jsdom';
/**
* HMAC signing utility. Methods are named after what it is to be signed, to
* allow for an easy to read code in the user application.
*
* @tutorial https://wiki.foxycart.com/v/2.0/hmac_validation
* @example const signer = new Signer(mySecret); // or const signer = new Signer(); signer.setSecret(mySecret);
* signer.signHtml('<html lang="en">...</html>'); // signs a URL
* signer.signFile("/var/www/html/src/.../index.html", "/var/www/html/target/.../index.html"); // signs an HTML file
* signer.signUrl("http://..."); // signs a URL
*/
export declare class Signer {
static readonly cartExcludes: string[];
static readonly cartExcludePrefixes: string[];
private __cartURL;
private __secret?;
/**
* Creates an instance of this class.
*
* @param secret OAuth2 client secret for your integration.
*/
constructor(secret?: string | null);
/**
* Sets the HMAC secret.
* It won't be possible to sign anything without this secret.
*
* @param secret OAuth2 client secret for your integration.
* @returns Signer to allow for convenient concatenation.
*/
setSecret(secret: string): Signer;
/**
* Signs a whole HTML snippet.
*
* @param htmlStr HTML snippet to sign.
* @returns the HTML snippet signed.
*/
signHtml(htmlStr: string): string;
/**
* Signs a file asynchronously.
*
* @param inputPath Path of the file to sign.
* @param outputPath Path of the file where the signed result will be stored.
* @param readFunc a function that should read from file
* @param writeFunc a function that should write to to file
* @returns a ParentNode object of the signed HTML.
*/
signFile(inputPath: string, outputPath: string, readFunc?: (arg0: string) => Promise<JSDOM>, writeFunc?: (path: string, content: string, callback: (err: any) => void) => void): Promise<ParentNode>;
/**
* Signs a query string.
* All query fields withing the query string will be signed, provided it is a proper URL and there is a code field
*
* @param urlStr Full URL including the query string that needs to be signed.
* @returns the signed query string.
*/
signUrl(urlStr: string): string;
/**
* Signs input name.
*
* @param name Name of the input element.
* @param code Product code.
* @param parentCode Parent product code.
* @param value Input value.
* @returns the signed input name.
*/
signName(name: string, code: string, parentCode?: string, value?: string | number): string;
/**
* Signs input value.
*
* @param name Name of the input element.
* @param code Product code.
* @param parentCode Parent product code.
* @param value Input value.
* @returns the signed value.
*/
signValue(name: string, code: string, parentCode?: string, value?: string | number): string;
/**
* Signs a product composed of code, name and value.
*
* @param code of the product.
* @param name name of the product.
* @param value of the product.
* @returns the signed product.
* @private
*/
private __signProduct;
/**
* Signs a single query argument to be used in `GET` requests.
*
* @param name of the argument.
* @param code of the product.
* @param value of the argument.
* @returns the signed query argument.
* @private
*/
private __signQueryArg;
/**
* Signs an input element.
*
* @param el the input element
* @param codes the codes dict object containing the code and parent code
* @returns the signed element
* @private
*/
private __signInput;
/**
* Signs a texArea element.
*
* @param el the textArea element.
* @param codes the codes dict object containing the code and parent code
* @returns the signed textarea element.
* @private
*/
private __signTextArea;
/**
* Signs all option elements within a Select element.
*
* @param el the select element.
* @param codes the codes dict object containing the code and parent code.
* @returns the signed select element.
* @private
*/
private __signSelect;
/**
* Sign an option element.
* Signatures are added to the value attribute on options.
* This function may also be used to sign radio buttons.
*
* @param el the option element to be signed.
* @param codes the codes dict object containing the code and parent code.
* @returns the signed option element.
* @private
*/
private __signOption;
/**
* Signs a radio button. Radio buttons use the value attribute to hold their signatures.
*
* @param el the radio button element.
* @param codes the codes dict object containing the code and parent code.
* @returns the signed radio button.
* @private
*/
private __signRadio;
/**
* Splits a string using the prefix pattern for foxy store.
* The prefix pattern allows for including more than a single product in a given GET or POST request.
*
* @param name the name to be separated into prefix and name.
* @returns an array with [prefix, name]
* @private
*/
private static __splitNamePrefix;
/**
* Retrieve a parent code value from a form, given a prefix.
*
* @param formElement the element with the code and parent code values.
* @param prefix the prefix used in hte element.
* @returns the parentCode
* @private
*/
private static __retrieveParentCode;
/**
* Signs a whole form element.
*
* @param formElement the form element to be signed.
* @private
*/
private __signForm;
/**
* Builds the value for the signed "name" attribute value given it components.
*
* @param name that was signed
* @param signature the resulting signature
* @param value of the field that, if equal to --OPEN-- identifies an editable field.
* @returns the signed value for the "name" attribute
* @private
*/
private static __buildSignedName;
/**
* Builds a signed name given it components.
*
* @param signature the resulting signature.
* @param value the value signed.
* @returns the built signed value
* @private
*/
private static __buildSignedValue;
/**
* Builds a signed query argument given its components.
*
* @param name the argument name.
* @param signature the resulting signature.
* @param value the value signed.
* @returns the built query string argument.
* @private
*/
private static __buildSignedQueryArg;
/**
* Returns the value of a field on the `--OPEN--` string if the value is not defined.
* Please, notice that `0` is an acceptable value.
*
* @param value of the field.
* @returns '--OPEN--' or the given value.
* @private
*/
private static __valueOrOpen;
/**
* Check if a href string is already signed. Signed strings contain two consecutive pipes
* followed by 64 hexadecimal characters.
*
* This method **does not validates the signature**.
* It only checks if the format of the string is evidence that it is signed.
*
* @param url the potentially signed URL.
* @returns true if the string format is evidence that it is already signed.
* @private
*/
private static __isSigned;
/**
* Returns the code from a URL or undefined if it does not contain a code.
*
* @param url the URL to retrieve the code from.
* @returns the code found, or undefined if no code was found.
* @private
*/
private static __getCodeFromURL;
/**
* Find all cart forms in a document fragment that contain an input named `code`.
*
* @param doc the document fragment potentially containing cart forms.
* @returns an array of the form elements found.
* @private
*/
private static __findCartForms;
/**
* Signs a document fragment. This method is used to sign HTML snippets.
*
* @param doc an HTML doc fragment
* @returns the signed HTML snippet
* @private
*/
private __fragment;
/**
* Signs a simple message. This function can only be invoked after the secret has been defined. The secret can be defined either in the construction method as in `new FoxySigner(mySecret)` or by invoking the setSecret method, as in `signer.setSecret(mySecret)`
*
*
* @param message the message to be signed.
* @returns signed message.
* @private
*/
private __message;
/**
* Checks if a name should be skipped.
*
* @param name that could be signed
* @returns it should be skipped, i.e. not be signed
* @private
*/
private __shouldSkipInput;
}