feat: adding new readme, contributing and license

CONTRIBUTING.md

@@ -0,0 +1,123 @@
+# Topsort.js
+
+This repository holds the official Topsort.js client library. This project is built with [TypeScript][typescript] and uses [Bun][bun] for package management and testing.
+
+[typescript]: https://www.typescriptlang.org
+[bun]: https://bun.sh/
+
+## How to contribute
+
+We'd love to accept your patches and contributions to this project. Bellow, you can find the guidelines on how to setup the project locally, test and code standards for top-notch contributions.
+
+## Table of Contents
+
+- [Reporting Issues](#reporting-issues)
+- [Local Installation](#local-installation)
+- [Running Locally](#running-locally)
+- [Building the SDK](#building-the-sdk)
+- [Tests](#tests)
+  - [Integration Tests](#integration-tests)
+- [Code Standards](#code-standards)
+- [Submitting contributions](#submitting-contributions)
+  - [Commit Messages](#commit-messages)
+- [Configuration](#configuration)
+- [License](#license)
+
+## Reporting issues
+
+Bugs, feature requests, and development-related questions should be directed to
+our [GitHub issue tracker](https://github.com/Topsort/topsort.js/issues).  If
+reporting a bug, please try and provide as much context as possible such as
+your operating system, Bun version, and anything else that might be relevant to
+the bug. For feature requests, please explain what you're trying to do, and
+how the requested feature would help you do that.
+
+Security related bugs can either be reported in the issue tracker, or if they
+are more sensitive, emailed to <[email protected]>.
+
+## Local Installation
+
+To install Topsort.js as a contributor, you need to have Bun installed on your machine. Follow the instructions on the [Bun website](https://bun.sh/) to install it.
+
+Clone the repository and install the dependencies:
+
+```sh
+git clone [email protected]:Topsort/topsort.js.git
+cd topsort.js
+bun install
+```
+
+## Running Locally
+
+In order to run a local application and test it against the local Topsort.js you need to do the following (after having the SDK all set up on local machine):
+
+On Topsort.js:
+```bash
+bun run build
+bun link
+```
+
+This will register a local `topsort.js` to be used on the secondary project.
+
+On the secondary project, if using bun, run:
+```bash
+bun link topsort.js
+```
+Or add it in dependencies in the package.json file:
+```sh
+"topsort.js": "link:topsort.js"
+```
+
+## Building the SDK
+
+To build the SDK, run the following command:
+
+```sh
+bun run build
+```
+
+This command cleans the `dist` directory and compiles the Typescript files into Javascript back to it
+
+## Tests
+
+### Integration Tests
+
+To run the integration tests, use the following command:
+
+```sh
+bun run test
+```
+
+## Code Standards
+
+We follow the coding standards set by Biome. Ensure your code follows these guidelines before submitting a pull request. You can run the formatter with the following command:
+```sh
+bun run format
+```
+
+To automatically fix issues:
+```sh
+bun run format:fix
+```
+
+## Submitting Contributions
+### Commit Messages
+
+We do conventional commits, so it will fail on checker with capital case after commit prefix. Refer to [Amannn's Github Action for Semantic Pull Request](https://github.com/amannn/action-semantic-pull-request) for details.
+
+1. Fork the repository.
+2. Create a new branch (git checkout -b feat/branch).
+3. Make your changes and commit them (git commit -m 'feat: adding new feature').
+4. Push to the branch (git push origin feat/branch).
+5. Open a pull request.
+
+## Configuration
+
+The SDK uses following configuration files:
+
+`tsconfig.json`: TypeScript configuration.
+
+`tsup.config.ts`: Configuration for the TSUP bundler.
+
+## License
+This project is licensed under the MIT License. See the [LICENSE](https://github.com/Topsort/topsort.js/blob/main/LICENSE) file for more details.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Topsort
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -8,46 +8,21 @@ This repository holds the official Topsort.js client library. This project is bu
 ## Table of Contents
 
 - [Installation](#installation)
-- [Running Locally](#running-locally)
 - [Usage](#usage)
   - [Creating an Auction](#auctions)
   - [Reporting an Event](#events)
-- [Development](#development)
-  - [Building the SDK](#building-the-sdk)
-  - [Running Integration Tests](#running-integration-tests)
-- [Configuration](#configuration)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Installation
 
-To install Topsort.js, you need to have Bun installed on your machine. Follow the instructions on the [Bun website](https://bun.sh/) to install it.
-
-Clone the repository and install the dependencies:
-
+With npm:
 ```sh
-git clone [email protected]:Topsort/topsort.js.git
-cd topsort.js
-bun install
-```
-
-## Running Locally
-
-In order to run a local application and test it against the local Topsort.js you need to do the following (after having the SDK all set up on local machine):
-
-On Topsort.js:
-```bash
-bun run build
-bun link
+npm install @topsort/topsort.js --save
 ```
-
-This will register a local `topsort.js` to be used on the secondary project.
-
-On the secondary project, if using bun, run:
-```bash
-bun link topsort.js
-```
-Or add it in dependencies in the package.json file:
+With yarn:
 ```sh
-"topsort.js": "link:topsort.js"
+yarn add @topsort/topsort.js --save
 ```
 
 ## Usage
@@ -57,9 +32,9 @@ Or add it in dependencies in the package.json file:
 To create an auction, use the createAuction function. Here is an example:
 
 ```js
-import { createAuction } from 'topsort.js';
+import { createAuction, TopsortAuction } from '@topsort/topsort.js';
 
-const auctionDetails = {
+const auctionDetails: TopsortAuction = {
   auctions: [
     {
       type: "listings",
@@ -87,27 +62,67 @@ createAuction(config, auctionDetails)
   .catch(error => console.error(error));
 ```
 
-Parameters:
+#### Parameters
 
 `config`: An object containing configuration details including the API key.
 
-`auctionDetails`: An object containing the details of the auction to be created, please refer to [Topsort's Auction API doc](https://docs.topsort.com/reference/createauctions).
+`auctionDetails`: An object containing the details of the auction to be created, please refer to [Topsort's Auction API doc](https://docs.topsort.com/reference/createauctions) for body specification.
+
+#### Sample response
+
+200:
+```json
+{
+  "results": [
+    {
+      "winners": [
+        {
+          "rank": 1,
+          "type": "product",
+          "id": "p_Mfk11",
+          "resolvedBidId": "WyJiX01mazExIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTMyNjYtY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=="
+        }
+      ],
+      "error": false
+    },
+    {
+      "winners": [],
+      "error": false
+    }
+  ]
+}
+```
+400:
+```json
+{
+  status: 400,
+  statusText: "No Content",
+  body: {
+    errCode: "bad_request",
+    docUrl: "https://docs.topsort.com/reference/errors",
+    message: "The request could not be parsed.",
+  },
+}
+```
 
 ### Events
 
 To report an event, use the reportEvent function. Here is an example:
 
 ```js
-import { reportEvent } from 'topsort.js';
+import { reportEvent, TopsortEvent } from 'topsort.js';
 
-const event = {
+const event: TopsortEvent = {
     impressions: [
       {
         resolvedBidId:
-          "ChAGaP5D2ex-UKEEBCOHwvDjEhABkF4FDAx0S5mMD2cO",
-        id: "1720706109.713344-53B92988-7A49-4679-B18E-465943B46150",
+          "ChAGaP5D2ex-UKEEBCOHwvDjEhABkF4FDAx0S5mMD2cOG0w9GhABkEnL2CB6qKIoqeItVgA_InsKd2h0dHBzOi8vd3d3LndlYmEuYmUvZnIvcHJvbW8uaHRtbD91dG1fc291cmNlPW15c2hvcGkmdXRtX21lZGl1bT1iYW5uZXJfMTI4MHg0MDAmdXRtX2NvbnRlbnQ9ZGlzcGxheSZ1dG1fY2FtcGFpZ249c29sZGVuEAU",
+        id: "1720706109.713344-53B92988-7A49-4679-B18E-465943B46149",
         occurredAt: "2024-07-11T13:55:09Z",
-        opaqueUserId: "38e0a5ff-9f8a-4e80-8969-e5e3f01348e9",
+        opaqueUserId: "38e0a5ff-9f8a-4e80-8969-e5e3f01348e8",
+        placement: {
+          path: "/categories/sports",
+        }
       },
     ],
   };
@@ -121,36 +136,38 @@ reportEvent(config, event)
   .catch(error => console.error(error));
 ```
 
-Parameters:
+#### Parameters
 
 `config`: An object containing configuration details including the API key.
 
-`event`: An object containing the details of the event to be reported, please refer to [Topsort's Event API doc](https://docs.topsort.com/reference/reportevents).
-
-## Development
-
-### Building the SDK
+`event`: An object containing the details of the event to be reported, please refer to [Topsort's Event API doc](https://docs.topsort.com/reference/reportevents) for body specification.
 
-To build the SDK, run the following command:
+#### Sample response
 
-```sh
-bun run build
+200:
+```json
+{
+    ok: true
+}
 ```
-
-This command cleans the `dist` directory and compiles the Typescript files into Javascript back to it
-
-### Running Integration Tests
-
-To run the integration tests, use the following command:
-
-```sh
-bun run test
+400:
+```json
+{
+  status: 204,
+  statusText: "No Content",
+  body: {
+    errCode: "bad_request",
+    docUrl: "https://docs.topsort.com/reference/errors",
+    message: "The request could not be parsed.",
+  },
+}
 ```
 
-## Configuration
+## Contributing
 
-The SDK uses following configuration files:
+We aim to cover the entire Topsort API, and contributions are always welcome. The calling pattern is well established, making the addition of new methods relatively straightforward. For more detailed guidelines on how to contribute, please refer to our [CONTRIBUTING.md](https://github.com/Topsort/topsort.js/blob/main/CONTRIBUTING.md).
 
-`tsconfig.json`: TypeScript configuration.
+Your help in enhancing the project is highly appreciated. Whether it’s reporting a bug, suggesting a new feature, or submitting a pull request, every bit of input helps us improve. Thank you for your support and happy coding!
 
-`tsup.config.ts`: Configuration for the TSUP bundler.
+## License
+This project is licensed under the MIT License. See the [LICENSE](https://github.com/Topsort/topsort.js/blob/main/LICENSE) file for more details.

package.json

@@ -7,7 +7,7 @@
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "author": "Márcio Barbosa <[email protected]>",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",