-
Notifications
You must be signed in to change notification settings - Fork 15
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
POAP Package documentation updated (#66)
* Adding new documentation * Adding new documentation * Adding new documentation * Adding new documentation * Adding new documentation * Adding new documentation * Adding new documentation * Adding new documentation * Deleted unused reference to protocol and put all poap to POAP * Added link to docuemntation * Added link to docuemntation * Added link to docuemntation * Adding new documentation * Adding new documentation
- Loading branch information
Showing
26 changed files
with
1,268 additions
and
71 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| v18 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,141 @@ | ||
| # Error Handling Documentation | ||
|
|
||
| This section documents the custom error classes defined for handling specific error scenarios while interacting with POAP tokens. | ||
|
|
||
| ## CodeAlreadyMintedError | ||
|
|
||
| The `CodeAlreadyMintedError` class is thrown when an attempt is made to mint a POAP token using a mint code that has already been used. | ||
|
|
||
| ```typescript | ||
| export class CodeAlreadyMintedError extends Error { | ||
| constructor(code: string) { | ||
| super(`Code: '${code}' already minted `); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## CodeExpiredError | ||
|
|
||
| The `CodeExpiredError` class is thrown when an attempt is made to use a mint code that has expired. | ||
|
|
||
| ```typescript | ||
| export class CodeExpiredError extends Error { | ||
| constructor(code: string) { | ||
| super(`Code: '${code}', has been expired`); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## FinishedWithError | ||
|
|
||
| The `FinishedWithError` class is thrown when a minting operation encounters an error. | ||
|
|
||
| ```typescript | ||
| export class FinishedWithError extends Error { | ||
| constructor(error: string, code: string) { | ||
| super( | ||
| `Code: '${code}', finished with error: '${error}', please try again later `, | ||
| ); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| These custom error classes allow for more precise error handling and better debugging, by providing specific error messages based on the type of error encountered. They extend the native JavaScript `Error` class and can be used in a similar manner, with the added benefit of POAP-specific error messages. | ||
|
|
||
| ### Example Usage | ||
|
|
||
| Below are examples demonstrating how one might use the `PoapsClient` class along with the custom error handling. | ||
|
|
||
| ```typescript | ||
| // Importing necessary classes and error types | ||
| import { | ||
| PoapsClient, | ||
| WalletMintInput, | ||
| EmailReservationInput, | ||
| } from '@poap-xyz/poap-client'; | ||
| import { | ||
| CodeAlreadyMintedError, | ||
| CodeExpiredError, | ||
| FinishedWithError, | ||
| } from '@poap-xyz/poap-errors'; | ||
|
|
||
| // Initializing the PoapsClient with providers | ||
| const poapsClient = new PoapsClient(compassProvider, tokensApiProvider); | ||
|
|
||
| // Defining the WalletMintInput | ||
| const walletMintInput: WalletMintInput = { | ||
| mintCode: 'some-mint-code', | ||
| address: '0x1234567890abcdef1234567890abcdef12345678', | ||
| }; | ||
|
|
||
| // Defining the EmailReservationInput | ||
| const emailReservationInput: EmailReservationInput = { | ||
| mintCode: 'some-other-mint-code', | ||
| email: '[email protected]', | ||
| }; | ||
|
|
||
| // Attempting to mint a POAP token synchronously | ||
| async function mintPoap() { | ||
| try { | ||
| const poap = await poapsClient.mintSync(walletMintInput); | ||
| console.log('POAP minted successfully:', poap); | ||
| } catch (error) { | ||
| if (error instanceof FinishedWithError) { | ||
| console.error('Error concluding the mint process:', error.message); | ||
| // Action: Notify the user about the error and suggest retrying later. | ||
| } else { | ||
| console.error('An unknown error occurred:', error.message); | ||
| // Action: Log the error and notify the user of a general error. | ||
| } | ||
| } | ||
| } | ||
|
|
||
| // Attempting to get the secret code for a mint code | ||
| async function getSecret() { | ||
| try { | ||
| const secretCode = await poapsClient.getSecretCode( | ||
| walletMintInput.mintCode, | ||
| ); | ||
| console.log('Secret code retrieved:', secretCode); | ||
| } catch (error) { | ||
| if (error instanceof CodeAlreadyMintedError) { | ||
| console.error('This mint code has already been used:', error.message); | ||
| // Action: Notify the user that the mint code has already been used. | ||
| } else if (error instanceof CodeExpiredError) { | ||
| console.error('This mint code has expired:', error.message); | ||
| // Action: Notify the user that the mint code has expired. | ||
| } else { | ||
| console.error('An unknown error occurred:', error.message); | ||
| // Action: Log the error and notify the user of a general error. | ||
| } | ||
| } | ||
| } | ||
|
|
||
| // Attempting to reserve a POAP via email | ||
| async function reservePoap() { | ||
| try { | ||
| const reservation = await poapsClient.emailReservation( | ||
| emailReservationInput, | ||
| ); | ||
| console.log('POAP reserved successfully:', reservation); | ||
| } catch (error) { | ||
| if (error instanceof CodeAlreadyMintedError) { | ||
| console.error('This mint code has already been used:', error.message); | ||
| // Action: Notify the user that the mint code has already been used. | ||
| } else if (error instanceof CodeExpiredError) { | ||
| console.error('This mint code has expired:', error.message); | ||
| // Action: Notify the user that the mint code has expired. | ||
| } else { | ||
| console.error('An unknown error occurred:', error.message); | ||
| // Action: Log the error and notify the user of a general error. | ||
| } | ||
| } | ||
| } | ||
|
|
||
| // Executing the mintPoap, getSecret, and reservePoap functions | ||
| mintPoap(); | ||
| getSecret(); | ||
| reservePoap(); | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,84 @@ | ||
| # Input Types Documentation | ||
|
|
||
| This section documents the input types used to fetch and manage POAPs . | ||
|
|
||
| ## PoapsSortFields | ||
|
|
||
| The `PoapsSortFields` enumeration defines the available fields by which POAPs can be sorted. | ||
|
|
||
| | Property | Value | Description | | ||
| | ---------- | ----------- | ------------------------------------------------------ | | ||
| | `MintedOn` | `minted_on` | Represents sorting by the date when a POAP was minted. | | ||
| | `Id` | `id` | Represents sorting by the ID of a POAP. | | ||
|
|
||
| ```typescript | ||
| export enum PoapsSortFields { | ||
| MintedOn = 'minted_on', | ||
| Id = 'id', | ||
| } | ||
| ``` | ||
|
|
||
| ## FetchPoapsInput | ||
|
|
||
| The `FetchPoapsInput` interface represents the input fields for fetching POAPs and extends `PaginationInput` to provide pagination capability. | ||
|
|
||
| | Property | Type | Description | | ||
| | --------------------- | ------------------ | ---------------------------------------------------------- | | ||
| | `name` | `string?` | Optional filter for the name of a POAP. | | ||
| | `chain` | `Chain?` | Optional filter for the blockchain chain of a POAP. | | ||
| | `mintedDateFrom` | `string?` | Optional filter for the start date when a POAP was minted. | | ||
| | `mintedDateTo` | `string?` | Optional filter for the end date when a POAP was minted. | | ||
| | `ids` | `number[]?` | Optional filter for specific POAP IDs. | | ||
| | `collectorAddress` | `string?` | Optional filter for the collector's address. | | ||
| | `dropId` | `number?` | Optional filter for a specific drop ID. | | ||
| | `sortField` | `PoapsSortFields?` | Field by which to sort the results. | | ||
| | `sortDir` | `Order?` | Direction in which to sort the results. | | ||
| | `filterByZeroAddress` | `boolean?` | Filter to include/exclude POAPs with zero addresses. | | ||
|
|
||
| ```typescript | ||
| export interface FetchPoapsInput extends PaginationInput { | ||
| name?: string; | ||
| chain?: Chain; | ||
| mintedDateFrom?: string; | ||
| mintedDateTo?: string; | ||
| ids?: number[]; | ||
| collectorAddress?: string; | ||
| dropId?: number; | ||
| sortField?: PoapsSortFields; | ||
| sortDir?: Order; | ||
| filterByZeroAddress?: boolean; | ||
| } | ||
| ``` | ||
|
|
||
| ## WalletMintInput | ||
|
|
||
| The `WalletMintInput` interface represents the input fields required to mint a POAP for an Ethereum wallet address. | ||
|
|
||
| | Property | Type | Description | | ||
| | ---------- | -------- | ---------------------------------------------- | | ||
| | `mintCode` | `string` | The mint code for the POAP. | | ||
| | `address` | `string` | The address of the wallet to mint the POAP to. | | ||
|
|
||
| ```typescript | ||
| export interface WalletMintInput { | ||
| mintCode: string; | ||
| address: string; | ||
| ``` | ||
| ## EmailReservationInput | ||
| The `EmailReservationInput` interface represents the input fields required to reserve a POAP via email. | ||
| | Property | Type | Description | | ||
| | ----------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `mintCode` | `string` | The mint code for the POAP, essential for identifying the specific POAP being reserved. | | ||
| | `email` | `string` | The email address for reserving the POAP, where the reservation confirmation and next steps will be sent. | | ||
| | `sendEmail` | `boolean?` | Optional field to specify whether to send an email notification. If set to true or omitted, an email containing the next steps will be sent to the provided email address. If set to false, no email will be sent, although the POAP is still reserved. | | ||
| ```typescript | ||
| export interface EmailReservationInput { | ||
| mintCode: string; | ||
| email: string; | ||
| sendEmail?: boolean; | ||
| } | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,57 @@ | ||
| # POAP | ||
|
|
||
| ## Description | ||
|
|
||
| The `POAP` class represents a POAP token with various attributes pertaining to the token itself, the drop it's associated with, and its ownership details. | ||
|
|
||
| ## Constructor | ||
|
|
||
| ```typescript | ||
| constructor(properties: PoapProperties) | ||
| ``` | ||
|
|
||
| Creates a new instance of the `POAP` class with specified properties. | ||
|
|
||
| ### Parameters | ||
|
|
||
| - `properties` (`PoapProperties`): An object containing all necessary properties to initialize the `POAP` instance. | ||
|
|
||
| ## Properties | ||
|
|
||
| | Property | Type | Description | | ||
| | ------------------ | -------- | ------------------------------------------------------------------------ | | ||
| | `id` | `number` | The unique identifier of the POAP token. | | ||
| | `collectorAddress` | `string` | The address of the collector owning the POAP token. | | ||
| | `transferCount` | `number` | The number of times the POAP token has been transferred. | | ||
| | `mintedOn` | `Date` | The date and time when the POAP token was minted. | | ||
| | `dropId` | `number` | The identifier of the drop associated with the POAP token. | | ||
| | `imageUrl` | `string` | The URL of the image representing the POAP token or the associated drop. | | ||
| | `city` | `string` | The city where the associated drop took place. | | ||
| | `country` | `string` | The country where the associated drop took place. | | ||
| | `description` | `string` | A description of the associated drop or the POAP token. | | ||
| | `startDate` | `Date` | The start date of the associated drop. | | ||
| | `endDate` | `Date` | The end date of the associated drop. | | ||
| | `name` | `string` | The name of the associated drop. | | ||
|
|
||
| ## PoapProperties Interface | ||
|
|
||
| The `PoapProperties` interface defines the shape of the object required by the constructor of the `POAP` class. | ||
|
|
||
| ```typescript | ||
| interface PoapProperties { | ||
| id: number; | ||
| collectorAddress: string; | ||
| transferCount: number; | ||
| mintedOn: Date; | ||
| dropId: number; | ||
| imageUrl: string; | ||
| city: string; | ||
| country: string; | ||
| description: string; | ||
| startDate: Date; | ||
| name: string; | ||
| endDate: Date; | ||
| } | ||
| ``` | ||
|
|
||
| Each property in the `PoapProperties` interface corresponds to a property in the `POAP` class, and their descriptions are as mentioned above in the Properties section. |
Oops, something went wrong.