init

Author: refarer

.gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+examples/node_modules
+examples/.env

.npmrc

@@ -0,0 +1 @@
+registry=https://registry.npmjs.org

CONTRIBUTING.md

@@ -7,18 +7,18 @@ We'd love to get patches from you!
 We follow the [GitHub Flow Workflow](https://guides.github.com/introduction/flow/)
 
 1. Fork the project
-1. Check out the `master` branch
+1. Check out the `main` branch
 1. Create a feature branch
 1. Write code and tests for your change
-1. From your branch, make a pull request against `twitter/repo-scaffolding/master`
+1. From your branch, make a pull request against `twitterdev/twitter-api-typescript-sdk/main`
 1. Work with repo maintainers to get your change reviewed
-1. Wait for your change to be pulled into `twitter/repo-scaffolding/master`
+1. Wait for your change to be pulled into `twitterdev/twitter-api-typescript-sdk/main`
 1. Delete your feature branch
 
 ## License
 
 By contributing your code, you agree to license your contribution under the
-terms of the APLv2: https://github.com/twitter/repo-scaffolding/blob/master/LICENSE
+terms of the APLv2: https://github.com/twitterdev/twitter-api-typescript-sdk/blob/main/LICENSE
 
 ## Code of Conduct
 

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2021 Twitter, Inc
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -1,8 +1,144 @@
-# An incredible project
+# Twitter API SDK for TypeScript
 
-This is the file you get to write to document your new project!
+## Introduction
 
-Also, don't forget to edit the couple of references in CONTRIBUTING.md that will need to be customized to link to this repo.
-Update the LICENSE file with the correct date and attribution.
+A TypeScript SDK for the Twitter API. This library is built with TypeScript developers in mind, but it also works with JavaScript.
 
-You also might want to create a .gitignore file to make things nicer.
+**Note: This SDK is in beta and is not ready for production**
+
+You can find examples of using the client in the [examples/](examples/) directory
+
+**Note: Only Twitter API V2 is supported**
+
+### Features
+
+- Full type information for requests and responses
+- OAuth2 support
+- Supports Node.js 14+. **Doesn't work in browser environments due to the Twitter API not supporting CORS**
+
+## Installing
+
+```
+npm install twitter-api-sdk
+```
+
+## Client
+
+To setup the client we will authenticate with a bearer-token as follows
+
+```typescript
+import { Client } from "twitter-api-sdk";
+
+const client = new Client("MY-BEARER-TOKEN");
+```
+
+For more information about authentication [go here](#authentication)
+
+## Examples
+
+### Consuming a stream
+
+```typescript
+import { Client } from "twitter-api-sdk";
+
+const client = new Client(process.env.BEARER_TOKEN);
+
+async function main() {
+  const stream = client.tweets.sampleStream({
+    "tweet.fields": ["author_id"],
+  });
+  for await (const tweet of stream) {
+    console.log(tweet.data?.author_id);
+  }
+}
+
+main();
+```
+
+### Getting a tweet
+
+```typescript
+import { Client } from "twitter-api-sdk";
+
+const client = new Client(process.env.BEARER_TOKEN);
+
+async function main() {
+  const tweet = await client.tweets.findTweetById("20");
+  console.log(tweet.data.text);
+}
+
+main();
+```
+
+## Streaming
+
+For endpoints that return a stream you get sent back an Async Generator which you can iterate over:
+
+```typescript
+const stream = client.tweets.sampleStream();
+
+for await (const tweet of stream) {
+  console.log(tweet.data.text);
+}
+```
+
+## Pagination
+
+For endpoints that have pagination you can
+
+```typescript
+const followers = client.users.usersIdFollowers("20");
+
+for await (const page of followers) {
+  console.log(page.data);
+}
+
+// This also works
+const followers = await client.users.usersIdFollowers("20");
+console.log(followers.data);
+```
+
+## Authentication
+
+This library supports App-only Bearer Token and OAuth 2.0
+
+You can see various examples on how to use the authentication in [examples/](examples/)
+
+## Getting Started
+
+Make sure you to turn on OAuth2 in your apps user authentication settings, and set the type of app to be a confidential client (Web App or Automated App or Bot).
+
+### Creating an Auth Client
+
+```typescript
+const authClient = new auth.OAuth2User({
+  client_id: process.env.CLIENT_ID,
+  client_secret: process.env.CLIENT_SECRET,
+  callback: "http://127.0.0.1:3000/callback",
+  scopes: ["tweet.read", "users.read", "offline.access"],
+});
+
+const client = new Client(authClient);
+```
+
+### Generating an Authentication URL
+
+```typescript
+const authUrl = authClient.generateAuthURL({
+  code_challenge_method: "s256",
+});
+```
+
+### Getting an Access Token
+
+Once the user has approved the OAuth flow, you will receive a `code` query parameter at the callback URL you specified.
+
+```typescript
+await authClient.requestAccessToken(code);
+```
+
+### Revoking an Access Token
+
+```typescript
+const response = await authClient.revokeAccessToken();
+```

examples/.npmrc

@@ -0,0 +1 @@
+registry=https://registry.npmjs.org

examples/README.md

@@ -0,0 +1,31 @@
+# Twitter API TypeScript SDK Examples
+
+## To run the examples
+
+Make sure you are in the `examples` directory
+
+Install the required packages
+
+```
+npm install
+```
+
+Next, create a `.env` file in the example directory and populate the following variables (You do not need them all for each example, for example `oauth2-bearer.ts` only requires a `BEARER_TOKEN`):
+
+```
+BEARER_TOKEN=my-bearer-token
+API_KEY=my-api-key
+API_SECRET_KEY=my-secret-key
+ACCESS_TOKEN=my-access-token
+ACCESS_TOKEN_SECRET=my-access-token-secret
+```
+
+Run the example with `ts-node`
+
+`npx ts-node *.ts`
+
+For example:
+
+```
+npx ts-node oauth2-bearer.ts
+```

examples/filtered-stream.ts

@@ -0,0 +1,34 @@
+// Copyright 2021 Twitter, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Client } from "twitter-api-sdk";
+import dotenv from "dotenv";
+
+dotenv.config();
+
+async function main() {
+  const client = new Client(process.env.BEARER_TOKEN as string);
+  await client.tweets.addOrDeleteRules(
+    {
+      add: [
+        { value: "cat has:media", tag: "cats with media" },
+        { value: "cat has:media -grumpy", tag: "happy cats with media" },
+        { value: "meme", tag: "funny things" },
+        { value: "meme has:images" },
+      ],
+    },
+    {
+      dry_run: true,
+    }
+  );
+  const rules = await client.tweets.getRules();
+  console.log(rules);
+  const stream = client.tweets.searchStream({
+    "tweet.fields": ["author_id", "geo"],
+  });
+  for await (const tweet of stream) {
+    console.log(tweet.data?.author_id);
+  }
+}
+
+main();

examples/oauth2-bearer.ts

@@ -0,0 +1,22 @@
+// Copyright 2021 Twitter, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Client } from "twitter-api-sdk";
+import * as dotenv from "dotenv";
+
+dotenv.config();
+
+async function main() {
+  const client = new Client(process.env.BEARER_TOKEN as string);
+  const { data } = await client.users.findUserByUsername("TwitterDev");
+  if (!data) throw new Error("Couldn't find user");
+  let count = 0;
+  for await (const followers of client.users.usersIdFollowers(data.id)) {
+    console.log(followers);
+    if (++count == 3) {
+      break;
+    }
+  }
+}
+
+main();

examples/oauth2-callback.ts

@@ -0,0 +1,60 @@
+// Copyright 2021 Twitter, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Client, auth } from "twitter-api-sdk";
+import express from "express";
+import dotenv from "dotenv";
+
+dotenv.config();
+
+const app = express();
+
+const authClient = new auth.OAuth2User({
+  client_id: process.env.CLIENT_ID as string,
+  client_secret: process.env.CLIENT_SECRET as string,
+  callback: "http://127.0.0.1:3000/callback",
+  scopes: ["tweet.read", "users.read", "offline.access"],
+});
+
+const client = new Client(authClient);
+
+const STATE = "my-state";
+
+app.get("/callback", async function (req, res) {
+  try {
+    const { code, state } = req.query;
+    if (state !== STATE) {
+      return res.status(500).send("State isn't matching");
+    }
+    await authClient.requestAccessToken(code as string);
+    res.redirect("/tweets");
+  } catch (error) {
+    console.log(error);
+  }
+});
+
+app.get("/login", async function (req, res) {
+  const authUrl = authClient.generateAuthURL({
+    state: STATE,
+    code_challenge: "challenge",
+  });
+  res.redirect(authUrl);
+});
+
+app.get("/tweets", async function (req, res) {
+  const tweets = await client.tweets.findTweetById("20");
+  res.send(tweets.data);
+});
+
+app.get("/revoke", async function (req, res) {
+  const refresh_token = authClient.refresh_token;
+  if (refresh_token) {
+    const response = await authClient.revokeAccessToken();
+    return res.send(response);
+  }
+  res.send("No access token to revoke");
+});
+
+app.listen(3000, () => {
+  console.log(`Go here to login: http://127.0.0.1:3000/login`);
+});