0.0.20 • Published 3 years ago

clip-sdk

Licence

MIT

Version

0.0.20

Deps

Size

20 kB

Vulns

Weekly

Summary Dependency Versions

SDK clip

Installation
Branching
Committing Changes
Committing Rules
Project Structure
API Documentation
Possible Statuses
Methods Reference

Installation

# npm install clip-sdk --registry https://npm-registry.conexa.ai

Branching

We use GitFlow branching model.

Your branch name should follow one of the following formats:

feature/feature-name for new features
fix/fix-name for bug fixes
chore/chore-name for chores
docs/docs-name for documentation
refactor/refactor-name for refactors
release/release-name for releases
revert/revert-name for reverts
test/test-name for tests
wip/wip-name for work in progress
ci/ci-name for continuous integration

Making Changes

Run yarn dev so you can compile Typescript(.ts) files in watch mode

yarn dev

Add your changes to TypeScript(.ts) files which are in the src folder. The files will be automatically compiled to JS if you are in watch mode.

Add tests for the new feature

Run yarn test:ts to make sure all Typescript tests pass.

yarn test:ts

Committing Changes

Run yarn commit to commit your changes. This will run commitizen which will guide you through the commit process.

yarn commit

Releasing

Run yarn release to release a new version of the package. This will automatically do the following:

Run yarn build to compile the Typescript files to JS
Run standard-version to generate a changelog and bump the version in package.json
- If you ran yarn release:major it will bump the major version
- If you ran yarn release:minor it will bump the minor version
- If you ran yarn release:patch it will bump the patch version
Run git push to push the changes to the remote repository
Run git push --tags to push the changes to the remote repository
Run npm publish to publish the package to the npm registry

We use The Conventional Commits specification. It is a convention that provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.

Commit types `required` `lowercase`

feat – a new feature is introduced with the changes

fix – a bug fix has occurred

chore – changes that do not relate to a fix or feature and don't modify src or test files (for example updating dependencies)

refactor – refactored code that neither fixes a bug nor adds a feature

docs – updates to documentation such as a the README or other markdown files

style – changes that do not affect the meaning of the code, likely related to code formatting such as white-space, missing semi-colons, and so on.

test – including new or correcting previous tests

perf – performance improvements

ci – continuous integration related

build – changes that affect the build system or external dependencies

revert – reverts a previous commit

echo ": some message"    # fails
echo "foo: some message" # fails
echo "FIX: some message" # fails
echo "fix: some message" # passes

Scope `optional` `lowercase`

echo "fix(SCOPE): some message" # fails
echo "fix(scope): some message" # passes

Description `required` `start in lowercase` `not ending in "."`

echo "fix:" # fails
echo "fix: some message." # fails
echo "fix(scope): Some message" # fails
echo "fix(scope): some message" # passes
echo "fix(scope): some Message" # passes

Examples:

echo "fix(.gitignore): added node_modules folder" 
echo "fix(controllers/auth): added frontend redirect params"
echo "revert(services/email): nodemailer version update"

Project Structure

.
├── src                               # Source files
│   ├── services                      # Services
│   │   ├── auth.service              # Authentication
│   │   ├── ....                      # Other services, for ex. checkout
│   ├── lib                           # General purpose utils and helpers
│   ├── index.ts                      # Package entry file
├── package.json
└── README.md

Possible Statuses

Property	Description
`CHECKOUT_CREATED`	The checkout has been created and is ready for the customer to complete the payment.
`CHECKOUT_EXPIRED`	The checkout has expired and can no longer be used to process a payment.
`CHECKOUT_CANCELED`	The checkout has been canceled and can no longer be used to process a payment.
`CHECKOUT_COMPLETED`	The checkout has been completed and the payment has been processed.
`CHECKOUT_PENDING`	The checkout is pending and the payment has not yet been processed.

Methods Reference

Initialization

The SDK exports a function called setAppConfig. Is used to initialize the API SDK and set global variables that will be used throughout the SDK. It takes an object with the following properties as input:

Property	Type	Description
`env`	`string`	Required. production / stage / development
`debug`	`boolean`	Optional. true / false
`userAgent`	`string`	Optional. User agent

import { setAppConfig } from 'clip-sdk';

setAppConfig({
	env: process.env.NODE_ENV,
	debug: true,
	userAgent: 'Tiendanube Client v1.0.0',
});

Instantiation

The main exported class of the API SDK is ClipSDK. This class provides access to the various services and functionality provided by the SDK, such as creating checkouts and retrieving transaction information.

To use the ClipSDK class, you will need to instantiate it with a token that is used to authenticate API requests. You can obtain a token by calling the authenticate function described below.

Once you have a token, you can create an instance of the ClipSDK class by calling the constructor with the token as an argument. For example:

import { ClipSDK, authenticate } from 'clip-sdk';

const token = await authenticate(apiKey, apiSecret);

const client = new ClipSDK(token);

// Now you can use the client to access the services
const transactions = await client.Transaction.getTransactions();

Authentication

The authenticate function returns a Promise that resolves with a string representing the token if the authentication is successful. If the authentication fails, the Promise will reject with an error.

Parameters

Parameter	Type	Description
`apiKey`	`string`	Required. Merchant API Key
`apiSecret`	`string`	Required. Merchant API Secret

import { authenticate } from 'clip-sdk';

try {
	const token = await authenticate(apiKey, apiSecret);
} catch (error) {
	throw new Error(httpStatus.UNAUTHORIZED)
}

Create Checkout

This method is used to create a new checkout, which is a payment request that can be used to process a payment.

The createCheckout function takes the following arguments as input:

Parameters

Parameter	Type	Description
`checkoutData`	`object`	Required. Checkout data
`environment`	`string`	Optional. Environment to use (production / stage / development)

Parameters Checkout Data

Property	Type	Description
`amount`	`number`	Required. Amount of the payment in the currency specified by the currency property.
`currency`	`string`	Required. Currency of the payment (e.g., "USD", "EUR").
`purchase_description`	`string`	Required. Description of the purchase being made.
`redirection_url`	`object`	Required. URLs to redirect the customer to after the checkout process is complete.
`redirection_url.success`	`string`	Required. URL to redirect the customer to upon successful completion of the checkout process.
`redirection_url.error`	`string`	Required. URL to redirect the customer to if there is an error during the checkout process.
`redirection_url.default`	`string`	Required. URL to redirect the customer to if the customer cancels the checkout process.
`metadata`	`object`	Required. Additional metadata for the checkout.
`metadata.me_reference_id`	`string`	Required. Reference ID for the checkout provided by the merchant.
`metadata.customer_info`	`object`	Required. Information about the customer.
`metadata.customer_info.name`	`string`	Required. Name of the customer.
`metadata.customer_info.email`	`string`	Required. Email address of the customer.
`metadata.customer_info.phone`	`string`	Required. Phone number of the customer.
`webhook_url`	`string`	Required. Instant payment notification from Clip
`billing_address`	`string`	Required. Buyer billing address
`billing_address.street`	`string`	Required.
`billing_address.outdoor_number`	`string`	Required.
`billing_address.interior_number`	`string`	Required.
`billing_address.locality`	`string`	Required.
`billing_address.city`	`string`	Required.
`billing_address.state`	`string`	Required.
`billing_address.zip_code`	`string`	Required.
`billing_address.country`	`string`	Required.
`billing_address.reference`	`string`	Required.
`billing_address.between_streets`	`string`	Required.
`billing_address.floor`	`string`	Required.
`shipping_address`	`string`	Optional. Buyer shipping address
`shipping_address.street`	`string`	Optional.
`shipping_address.outdoor_number`	`string`	Optional.
`shipping_address.interior_number`	`string`	Optional.
`shipping_address.locality`	`string`	Optional.
`shipping_address.city`	`string`	Optional.
`shipping_address.state`	`string`	Optional.
`shipping_address.zip_code`	`string`	Optional.
`shipping_address.country`	`string`	Optional.
`shipping_address.reference`	`string`	Optional.
`shipping_address.between_streets`	`string`	Optional.
`shipping_address.floor`	`string`	Optional.
`source`	`string`	Required. Source of request

Response

Property	Type	Description
`payment_request_id`	`string`	ID of the payment request.
`payment_request_url`	`string`	URL of the payment request page.
`object_type`	`string`	Type of object being returned (e.g., "checkout").
`status`	`string`	Current status of the checkout.
`last_status_message`	`string`	Last status message for the checkout.
`created_at`	`string`	Date and time at which the checkout was created.
`modified_at`	`string`	Date and time at which the checkout was last modified.
`expired_at`	`string`	Date and time at which the checkout will expire.

import { ClipSDK } from 'clip-sdk';

const client = new ClipSDK(token);

const checkoutData = {
  "amount": 3,
  "currency": "MXN",
  "purchase_description": "Hamburguesas 2x1 + 50% descuento",
  "redirection_url": {
     "success": "https://merchant_ecoomerce.com/redirection/success",
     "error": "https://merchant_ecoomerce.com/redirection/error",
     "default": "https://merchant_ecoomerce.com/redirection/default"
  },
  "metadata": {
    "me_reference_id": "OID123456789",
    "customer_info": {
      "name": "Alejandro Lee",
      "email": "buyer@hotmail.com",
      "phone": 5520686868
    }
    "billing_address": {
      "street": "streetTest",
      "outdoor_number": "23a",
      "interior_number": "1234",
      "locality": "colonyTest",
      "city": "cityTest",
      "state": "stateTest",
      "zip_code": "54117",
      "country": "cuntryTest",
      "reference": "referenceTest",
      "between_streets": "street 1 and street 2",
      "floor": "floorTest"
    },
    "shipping_address": {
      "street": "streetTest",
      "outdoor_number": "23a",
      "interior_number": "1234",
      "locality": "colonyTest",
      "city": "cityTest",
      "state": "stateTest",
      "zip_code": "54117",
      "country": "cuntryTest",
      "reference": "referenceTest",
      "between_streets": "street 1 and street 2",
      "floor": "floorTest"
    },
    "source": "tiendanube"
   },
   "webhook_url": "https://merchant_ecoomerce.com/api/v1/webhooks/ipn";
}

const checkout = await client.Checkout.createCheckout(checkoutData);

Get Checkout

This method is used to retrieve information about a checkout that was previously created. The getCheckout function takes the following arguments as input:

Parameters

Property	Type	Description
`paymentRequestId`	`string`	Required. ID of the payment request.

Response

Property	Type	Description
`payment_request_id`	`string`	ID of the payment request.
`payment_request_url`	`string`	URL of the payment request page.
`object_type`	`string`	Type of object being returned (e.g., "checkout").
`status`	`string`	Current status of the checkout.
`last_status_message`	`string`	Last status message for the checkout.
`created_at`	`string`	Date and time at which the checkout was created.
`modified_at`	`string`	Date and time at which the checkout was last modified.
`expired_at`	`string`	Date and time at which the checkout will expire.
`amount`	`number`	Amount of the payment in the currency specified by the currency property.
`currency`	`string`	Currency of the payment (e.g., "USD", "EUR").
`purchase_description`	`string`	Description of the purchase being made.
`redirection_url`	`object`	URLs to redirect the customer to after the checkout process is complete.
`redirection_url.success`	`string`	URL to redirect the customer to upon successful completion of the checkout process.
`redirection_url.error`	`string`	URL to redirect the customer to if there is an error during the checkout process.
`redirection_url.default`	`string`	URL to redirect the customer to if the customer cancels the checkout process.
`metadata`	`object`	Additional metadata for the checkout.
`metadata.me_reference_id`	`string`	Reference ID for the checkout provided by the merchant.
`metadata.customer_info`	`object`	Information about the customer.
`metadata.customer_info.name`	`string`	Name of the customer.
`metadata.customer_info.email`	`string`	Email address of the customer.
`metadata.customer_info.phone`	`string`	Phone number of the customer.

import { ClipSDK } from 'clip-sdk';

const client = new ClipSDK(token);

const checkout = await client.Checkout.getCheckout(paymentRequestId);