Skip to content

Commit

Permalink
3.0.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@AlexanderEpolite
AlexanderEpolite committed Apr 10, 2023
1 parent 1f2992c commit e453bdc
Show file tree
Hide file tree
Showing 4 changed files with 139 additions and 197 deletions.
101 changes: 43 additions & 58 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,85 +19,70 @@ This has built-in types.

## Usage

First, create a TempMail object:
```js
const tempmail = new TempMail();

//if you have a TempMail Plus account, you can add it here:
const tempmail = new TempMail("24-number id", "32-character token");
```

### Create inbox

To create an inbox, you can use one of the following two functions:
To create an inbox:
```js
//with callback
createInbox((inbox, err) => {
if(err) {
return console.error(err);
}

console.log(`Created new inbox: ${inbox.address}, token: ${inbox.token}`);
}, false); //set to true to use Rush Mode domains.

//read more about Rush Mode: https://tempmail.lol/news/2022/08/03/introducing-rush-mode-for-tempmail/

//async
createInboxAsync(false).then((inbox) => { //set to true to use Rush Mode domains.
console.log(`Created new inbox: ${inbox.address}, token: ${inbox.token}`);
//simply, you can use the following function
tempmail.createInbox().then(inbox => {
console.log(`Inbox: ${inbox.address} with a token of ${inbox.token}`);
});

//await
const inbox = await createInboxAsync();
```
//there are some advanced options as well

You can also specify a parameter after the rush mode parameter to specify the domain of the inbox. For example:
```js
createInbox((inbox, err) => {
if(err) {
return console.error(err);
}

console.log(`Created new inbox: ${inbox.address}, token: ${inbox.token}`);
}, false, "example.com");
//whether or not to create a community address
const community = false;
tempmail.createInbox(community);


//or to use a custom domain
const domain = "example.com";
tempmail.createInbox(false, domain);
```

Will create an inbox with the address `example.com`.
Note that all inboxes expire after 10 minutes since last check, with a hard expiry limit of one hour that cannot be bypassed.

TempMail Plus subscribers can extend this to TEN hours, but the 10-minute check rule still applies.

### Retrieve emails

To get the emails (you can also pass in the Inbox object instead of a token string):
To get the emails in an inbox:
```js
//with callback
checkInbox("token", (emails) => {
emails.forEach((e) => {
console.log(JSON.stringify(e, null, 4));
});
});

//async
checkInboxAsync("token").then((emails) => {
emails.forEach((e) => {
console.log(JSON.stringify(e, null, 4));
});
//you can also pass through the Inbox object instead of the token string
const emails = tempmail.checkInbox("<TOKEN>").then((emails) => {
if(!emails) {
console.log(`Inbox expired since "emails" is undefined...`);
return;
}

console.log(`We got some emails!`);

for(let i = 0; i < emails.length; i++) {
console.log(`email ${i}: ${JSON.stringify(emails[i])}`);
}
});

//await
const emails = await checkInboxAsync("token");
```

### Custom Domains

Starting September 1st, you can use custom domains with this API. To use a custom domain, you can use the following function:
```js
//with callback
checkCustomInbox("example.com", "abcdefg...", (emails) => {
emails.forEach((e) => {
console.log(JSON.stringify(e, null, 4));
});
});
#### Note: you will need to be a TempMail Plus subscriber to use custom domains!

//async
checkCustomInboxAsync("example.com", "abcdefg...").then((emails) => {
emails.forEach((e) => {
console.log(JSON.stringify(e, null, 4));
});
```js
tempmail.checkCustomDomain("example.com", "token").then(emails => {
//woohoo, emails!
});

//await
const emails = await checkCustomAsync("example.com", "abcdefg...");
```

You can obtain a token by visiting https://tempmail.lol/custom.html

Custom domains will NOT alert you if the token is invalid.
7 changes: 4 additions & 3 deletions SECURITY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,13 @@
The current supported versions of TempMail are below:

| Version | Supported |
| ------- | ------------------ |
| 2.x.x | :white_check_mark: |
|---------|--------------------|
| 3.x.x | :white_check_mark: |
| 2.x.x | :x: |
| 1.x.x | :x: |

If you are not on the current major version, it is recommended that you upgrade, as support for that version of the library may be dropped at any time by the server.

## Reporting a Vulnerability

You can report a vulnerability on GitHub Issues or by emailing [security@exploding.email](mailto:security@exploding.email).
You can report a vulnerability on GitHub Issues or by emailing [security@bananacrumbs.us](mailto:security@bananacrumbs.us).
2 changes: 1 addition & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "tempmail.lol",
"version": "2.0.3",
"version": "3.0.0",
"description": "API to generate temporary email addresses.",
"main": "dist/index.js",
"types": "dist/index.d.ts",
Expand Down
226 changes: 91 additions & 135 deletions src/index.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,154 +7,110 @@ import Email from "./Email";

const BASE_URL = "https://api.tempmail.lol";

/**
* Create a new Inbox.
* @param cb {function} Callback function.
* @param rush {boolean} (optional) Enable Rush Mode (see https://tempmail.lol/news/2022/08/03/introducing-rush-mode-for-tempmail/).
* @param domain {string} (optional) use a specific domain from the website.
*
* @throws {Error} if the custom domain does not exist or `rush` and `domain` are present.
*/
function createInbox(cb: (inbox: Inbox | undefined, err: Error | null) => any, rush = false, domain: string | undefined = undefined): void {
export class TempMail {

if(rush && domain !== undefined) {
throw new Error("You cannot specify both a custom domain and rush mode.");
}

let url = `${BASE_URL}/generate`;

if(rush) {
url += "/rush";
} else if(domain !== undefined) {
url += `/${domain}`;
}
constructor(
private bananacrumbs_id?: string,
private bananacrumbs_mfa?: string,
) {}

fetch(url).then(res => res.json()).then((json) => {
const inbox = new Inbox(json.address, json.token);
if(json.error) {
cb(undefined, new Error(json.error));
private async makeRequest(url: string): Promise<any> {

let headers = {
"User-Agent": "TempMailJS/3.0.0"
};

//if the user is a TempMail Plus subscriber, add the credentials here
if(this.bananacrumbs_id) {
headers["X-BananaCrumbs-ID"] = this.bananacrumbs_id;
headers["X-BananaCrumbs-MFA"] = this.bananacrumbs_mfa;
}
cb(inbox, null);
}).catch((err) => {
cb(undefined, err);
});
}

/**
* Create a new Inbox asynchronously.
*
* @param rush {boolean} (optional) Enable Rush Mode (see https://tempmail.lol/news/2022/08/03/introducing-rush-mode-for-tempmail/).
* @param domain {string} (optional) use a specific domain from the website.
* @returns {Promise<Inbox>} Promise with the Inbox.
* @throws {Error} if the custom domain does not exist or `rush` and `domain` are present.
*/
async function createInboxAsync(rush: boolean = false, domain: string | undefined = undefined): Promise<Inbox> {
if(rush && domain !== undefined) {
throw new Error("You cannot specify both a custom domain and rush mode.");

const raw = await fetch(BASE_URL + url, {
headers,
});

//check for errors
if(raw.status === 402) { //no time left
throw new Error("BananaCrumbs ID has no more time left.");
} else if(raw.status === 400 && this.bananacrumbs_id) { //invalid credentials
throw new Error("Invalid BananaCrumbs credentials provided.");
} else if(!raw.ok) { //other error
throw new Error(`An error occurred while attempting to fetch data from the API: ${await raw.text()}`);
}

return await raw.json();
}

let url = `${BASE_URL}/generate`;

if(rush) {
url += "/rush";
} else if(domain !== undefined) {
url += `/${domain}`;
/**
* Create a new inbox.
*
* @param community {boolean} true to use community (formerly "rush mode") domains
* @param domain {string} the specific domain to use.
* @returns {Inbox} the Inbox object with the address and token.
*/
async createInbox(community?: boolean, domain?: string): Promise<Inbox> {
let url: string;

//craft the URL to use
if(domain) {
url = "/generate/" + domain;
} else {
url = "/generate" + (community ? "/rush" : "");
}

const r = await this.makeRequest(url);

return {
address: r.address,
token: r.token,
};
}

const res = await fetch(url);
const json = await res.json();

if(json.error) throw new Error(json.error);

return new Inbox(json.address, json.token);
}

/**
* Check for new emails on an Inbox.
* @param inbox {Inbox | string} Inbox or token string to check.
* @param cb {function} Callback function.
*/
function checkInbox(inbox: Inbox | string, cb: (emails: Email[], err: Error | null) => any): void {

//convert the token to an Inbox
if(typeof inbox === "string") {
inbox = new Inbox("", inbox);
/**
* Check an inbox for emails.
*
* @param authentication
* @returns {Email[] | undefined} the Email array, or undefined if the inbox has expired.
*/
async checkInbox(authentication: string | Inbox): Promise<Email[] | undefined> {
const token = authentication instanceof Inbox ? authentication.token : authentication;

const r = await this.makeRequest(`/auth/${token}`);

if(r.token && r.token === "invalid") {
return undefined;
}

return r.email;
}

fetch(`${BASE_URL}/auth/${inbox.token}`).then(res => res.json()).then(json => {
if(json.token === "invalid") {
cb([], new Error("Invalid token"));
/**
* Check a custom domain.
*
* Note that this requires a TempMail Plus subscription, as well as being logged in through `this` object.
*
* @param domain {string} the domain to check.
* @param token {string} the pre-SHA512 token to use for authentication.
* @returns {Email[]} the emails, or undefined if there was an issue checking.
*/
async checkCustomDomain(domain: string, token: string): Promise<Email[]> {

const r = await this.makeRequest(`/custom/${token}/${domain}`);

let emails: Email[];

if(r.email === null) {
emails = [];
} else {
emails = r.email;
}
if(json.email === null) {
return cb([], null);
}
const emails = json.email.map((email: Email) => new Email(email.from, email.to, email.subject, email.body, email.html, email.date, email.ip));
cb(emails, null);
});
}

/**
* Check for new emails on an Inbox asynchronously.
*
* @param inbox {Inbox | string} Inbox or token string to check.
* @returns {Promise<Email[]>} Promise with the emails.
* @throws {Error} If the token is invalid.
*/
async function checkInboxAsync(inbox: Inbox | string): Promise<Email[]> {

//convert the token to an Inbox
if(typeof inbox === "string") {
inbox = new Inbox("", inbox);

return emails;
}

const res = await fetch(`${BASE_URL}/auth/${inbox.token}`);
const json = await res.json();
if(json.token === "invalid") {
throw new Error("Invalid token");
}
if(json.email === null) {
return [];
}
return json.email.map((email: Email) => new Email(email.from, email.to, email.subject, email.body, email.html, email.date, email.ip));
}

/**
* Check a custom inbox.
*
* NOTE: this method will not return anything indicating if the token is invalid.
*
* @param domain {string} Domain to check.
* @param key {string} The key for the domain generated by the website.
* @param cb {function} Callback function.
*/
function checkCustomInbox(domain: string, key: string, cb: (emails: Email[]) => any): void {
fetch(`${BASE_URL}/custom/${key}/${domain}`).then(res => res.json()).then(json => {
const emails = json.email.map((email: Email) => new Email(email.from, email.to, email.subject, email.body, email.html, email.date, email.ip));
cb(emails);
});
}

/**
* Check a custom inbox asynchronously.
*
* NOTE: this method will not return anything indicating if the token is invalid.
*
* @param domain {string} Domain to check.
* @param key {string} The key for the domain generated by the website.
*
* @returns {Promise<Email[]>} Promise with the emails.
*/
async function checkCustomInboxAsync(domain: string, key: string): Promise<Email[]> {
const res = await fetch(`${BASE_URL}/custom/${key}/${domain}`);
const json = await res.json();
return json.email.map((email: Email) => new Email(email.from, email.to, email.subject, email.body, email.html, email.date, email.ip));
}

export {
Inbox,
Email,

createInbox, createInboxAsync,
checkInbox, checkInboxAsync,
checkCustomInbox, checkCustomInboxAsync
Email, Inbox
};

0 comments on commit e453bdc

Please sign in to comment.