sidechat.js 2.6.6 → 2.7.0

package/docs/tutorials/Authentication.md

@@ -1,53 +1,64 @@
-There are two supported methods of authenticating a Sidechat.js API client.  We recommend the automatic method, but you may choose to use the manual method if your project involves multiple instances of `SidechatAPIClient`. 
-
-Go ahead and import `SidechatAPIClient` from the module:
-
-```javascript
-import { SidechatAPIClient } from "sidechat.js";
-```
-
-
-### Automatic method
-
-First, create a new instance of the client:
-
-```javascript
-const API = new SidechatAPIClient();
-```
-
-For existing users, logging in is trivial.  First, send the user a verification code to their phone number.  Make sure the passed phone number is in a 10-digit format with no dashes, spaces, or parentheses:
-
-```javascript
-const phoneNumber = /* User's phone number */;
-await API.loginViaSMS(phoneNumber);
-```
-
-Then once the user has inputted the 6-digit code into your application, verify it with the API:
-
-```javascript
-const code = /* SMS verification code */;
-await API.verifySMSCode(phoneNumber, code);
-```
-
-If the user already exists, calling those two functions will set the user token and all requests from here on out using this instance of the API client will be automatically authenticated.
-
-If the user has not used Sidechat before, the `verifySMSCode` will return a `registrationID`, which you should store and then use to call the `setAge` function:
-
-```javascript
-// Here "res" refers to the result of verifySMSCode()
-const { registration_id } = res;
-await API.setAge(18, registration_id);
-```
-
-Now the user should be logged in properly and future requests will be automatically authenticated.  You may still need to [add an email address](tutorial-Email%20Registration.html) for most functionality.
-
-### Manual method
-
-You can pass a user token directly to the constructor initialization:
-
-```javascript
-const token = /* User bearer token as a string */;
-const API = new SidechatAPIClient(token);
-```
-
+There are two supported methods of authenticating a Sidechat.js API client.  We recommend the automatic method, but you may choose to use the manual method if your project involves multiple instances of `SidechatAPIClient`. 
+
+Go ahead and import `SidechatAPIClient` from the module:
+
+```javascript
+import { SidechatAPIClient } from "sidechat.js";
+```
+
+
+### Automatic method
+
+First, create a new instance of the client:
+
+```javascript
+const API = new SidechatAPIClient();
+```
+
+The official app sends an identifier for the device along with every request, so it's a good idea to do the same.  This should be something that stays the same every time your app runs on the same device:
+
+```javascript
+const deviceID = /* Stable ID for this device */;
+API.setDeviceIdentifier(deviceID);
+```
+
+For existing users, logging in is trivial.  First, send the user a verification code to their phone number.  Make sure the passed phone number is in a 10-digit format with no dashes, spaces, or parentheses:
+
+```javascript
+const phoneNumber = /* User's phone number */;
+await API.loginViaSMS(phoneNumber);
+```
+
+If the code never shows up, you can try sending it through Sidechat's backup SMS route by passing `true` as the second parameter.  Sometimes the server will also ask for a captcha before it sends a code, in which case the response will have an `error_code` of `"captcha_required"`.  sidechat.js can't solve those yet, so the best you can do is ask the user to try again later.
+
+Then once the user has inputted the 6-character code into your application, verify it with the API.  Codes can include letters, but they're not case-sensitive:
+
+```javascript
+const code = /* SMS verification code */;
+await API.verifySMSCode(phoneNumber, code);
+```
+
+If the user already exists, calling those two functions will set the user token and all requests from here on out using this instance of the API client will be automatically authenticated.
+
+If the user has not used Sidechat before, the `verifySMSCode` will return a `registrationID`, which you should store and then use to call the `setAge` function:
+
+```javascript
+// Here "res" refers to the result of verifySMSCode()
+const { registration_id } = res;
+await API.setAge(18, registration_id);
+```
+
+`setAge` also sends the user's time zone, which defaults to the system time zone.  If your code is running somewhere other than the user's device (like a server), pass their time zone as the third parameter.
+
+Now the user should be logged in properly and future requests will be automatically authenticated.  You may still need to [add an email address](tutorial-Email%20Registration.html) for most functionality.
+
+### Manual method
+
+You can pass a user token directly to the constructor initialization:
+
+```javascript
+const token = /* User bearer token as a string */;
+const API = new SidechatAPIClient(token);
+```
+
 All requests from here on out using this instance of the API client will automatically use the token passed to the constructor.

package/docs/tutorials/Email Registration.md

@@ -1,16 +1,19 @@
-> You can only start this process once you have [authenticated as a user](tutorial-Authentication.html).
-
-Start by sending a verification email to the user:
-
-```javascript
-const email = /* User's email address */;
-await API.registerEmail(email);
-```
-
-Once the user has clicked the link in the verification email, verify that they've clicked it:
-
-```javascript
-await API.checkEmailVerification();
-```
-
-You should be verified!
+> You can only start this process once you have [authenticated as a user](tutorial-Authentication.html).
+
+Start by sending a verification email to the user:
+
+```javascript
+const email = /* User's email address */;
+await API.registerEmail(email);
+```
+
+Once the user has clicked the link in the verification email, verify that they've clicked it:
+
+```javascript
+await API.checkEmailVerification();
+```
+
+You should be verified!
+
+> ### NOTE
+> There's also a `verifyEmailWithThirdParty` method that verifies the user's school email by signing in with Google or Microsoft instead of clicking a link.  It's experimental and I haven't tested it yet, so use it at your own risk.

package/docs/tutorials/Feeds and Pagination.md

@@ -0,0 +1,45 @@
+> You'll need to be [authenticated as a user](tutorial-Authentication.html) before fetching any posts.
+
+There are two kinds of feeds: the home feed, which mixes posts from every group the user is in, and group feeds, which only show posts from one group.
+
+### Home feed
+
+The home feed can be sorted by `"for_you"`, `"hot"`, or `"recent"`:
+
+```javascript
+const feed = await API.getHomeFeed("for_you");
+```
+
+The official YikYak app also passes the ID of the user's school group as the second parameter.  That's the group with a `group_join_type` of `"email_domain"`, which you can find with `getGroups()`.
+
+Not everything in the home feed is a post.  Each item in `feed.feed_items` has an `item_type`, and some of them are things like group suggestions instead of posts.  If you only care about posts, filter the rest out:
+
+```javascript
+const posts = feed.feed_items.filter((i) => i.item_type == "post").map((i) => i.post);
+```
+
+### Group feeds
+
+Group feeds can be sorted by `"hot"`, `"recent"`, or `"top"`:
+
+```javascript
+const groupID = /* ID of a group */;
+const { posts } = await API.getGroupPosts(groupID, "hot");
+```
+
+Top posts can also be narrowed down to a time period of `"day"`, `"week"`, `"month"`, `"year"`, or `"all_time"`:
+
+```javascript
+await API.getGroupPosts(groupID, "top", undefined, "week");
+```
+
+### Loading more
+
+Feeds come back one page at a time along with a `cursor`.  To get the next page, pass that cursor back into the same function:
+
+```javascript
+const firstPage = await API.getGroupPosts(groupID, "recent");
+const secondPage = await API.getGroupPosts(groupID, "recent", firstPage.cursor);
+```
+
+The home feed (`getHomeFeed`) and activity (`getActivity`) work the same way.

package/docs/tutorials/Posting and Media.md

@@ -0,0 +1,63 @@
+> You'll need to be [authenticated as a user](tutorial-Authentication.html) and a member of the group you're posting in.
+
+### Text posts
+
+The simplest post just needs some text and a group ID:
+
+```javascript
+const groupID = /* ID of the group to post in */;
+const post = await API.createPost("hello world", groupID);
+```
+
+`createPost` has a few more optional parameters, in this order: a list of assets, whether DMs are disabled, whether comments are disabled, whether the post is anonymous, the ID of a post to repost, a list of poll options, and a list of link attachment IDs.  So an anonymous poll looks like this:
+
+```javascript
+await API.createPost("best dining hall?", groupID, [], false, false, true, undefined, [
+  "North",
+  "South",
+]);
+```
+
+Users can only make two posts a minute.  If a post gets rejected, `createPost` throws a `SidechatAPIError` with the server's explanation as its message, so it's a good idea to show that message to the user.
+
+### Comments
+
+Commenting on a post works similarly:
+
+```javascript
+await API.createComment(post.id, "first", groupID);
+```
+
+Replies are where it gets a little confusing.  To reply to a top-level comment, pass its ID as the fourth parameter.  To reply to a reply, pass the reply's ID as the fourth parameter and the ID of the top-level comment it lives under as the fifth.
+
+### Images and videos
+
+Uploading media takes two steps: upload the file with `uploadAsset`, then attach it to a post.  `uploadAsset` is built for React Native, so it expects a local file URI:
+
+```javascript
+const url = await API.uploadAsset(/* local file URI */, "image/jpeg", "photo.jpg");
+const assetID = url.split("/").pop();
+```
+
+Then pass an asset object to `createPost`.  The width and height should be the image's real dimensions:
+
+```javascript
+await API.createPost("look at this", groupID, [
+  { id: assetID, type: "image", content_type: "jpeg", width: 1080, height: 1350 },
+]);
+```
+
+Videos work the same way, with a `type` of `"video"` and a `content_type` of `"mp4"` or `"mov"`.  They have to be under 50MB.  After posting, the server processes the video, which usually takes a few seconds.  You can tell where it's at from the asset's `vod_status`, which goes from `not_started` to `ingest` to `complete`.  Once it's complete, the asset's `url` points to an HLS stream (an `.m3u8` file), so you'll need a video player that supports HLS to play it.
+
+### Links
+
+Links are added as attachments.  Create the attachment first, then pass its ID to `createPost`:
+
+```javascript
+const attachment = await API.createLinkAttachment("https://github.com/micahlt/sidechat.js");
+await API.createPost("cool library", groupID, [], false, false, false, undefined, undefined, [
+  attachment.id,
+]);
+```
+
+The attachment comes back with a title, a shortened `display_url`, and a preview image, so you can show the user a preview before they post.  YouTube links get a `type` of `"youtube"` instead of `"link"`.

package/package.json

@@ -1,55 +1,55 @@
-{
-  "name": "sidechat.js",
-  "version": "2.6.6",
-  "description": "A reverse-engineered API wrapper for Sidechat",
-  "type": "module",
-  "source": "./src/index.js",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.mts",
-        "default": "./dist/index.mjs"
-      },
-      "require": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.cjs"
-      }
-    },
-    "./src/types": {
-      "types": "./dist/types/SidechatTypes.d.ts",
-      "default": "./src/types/SidechatTypes.js"
-    }
-  },
-  "scripts": {
-    "build": "rollup -c",
-    "dev": "rollup -c --watch",
-    "docs": "jsdoc --configure jsdoc.json --verbose",
-    "prepublish": "tsc",
-    "typegen": "tsc"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/micahlt/sidechat.js.git"
-  },
-  "author": "Micah Lindley",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/micahlt/sidechat.js/issues"
-  },
-  "homepage": "https://github.com/micahlt/sidechat.js#readme",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "devDependencies": {
-    "clean-jsdoc-theme": "^4.3.0",
-    "dotenv": "^16.4.7",
-    "prompt-sync": "^4.2.0",
-    "rollup": "^2.79.2",
-    "rollup-plugin-copy": "^3.5.0",
-    "typescript": "^5.7.3"
-  },
-  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
-}
+{
+  "name": "sidechat.js",
+  "version": "2.7.0",
+  "description": "A reverse-engineered API wrapper for Sidechat",
+  "type": "module",
+  "source": "./src/index.js",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./src/types": {
+      "types": "./dist/types/SidechatTypes.d.ts",
+      "default": "./src/types/SidechatTypes.js"
+    }
+  },
+  "scripts": {
+    "build": "rollup -c",
+    "dev": "rollup -c --watch",
+    "docs": "jsdoc --configure jsdoc.json --verbose",
+    "prepublish": "tsc",
+    "typegen": "tsc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/micahlt/sidechat.js.git"
+  },
+  "author": "Micah Lindley",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/micahlt/sidechat.js/issues"
+  },
+  "homepage": "https://github.com/micahlt/sidechat.js#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "clean-jsdoc-theme": "^4.3.0",
+    "dotenv": "^16.4.7",
+    "prompt-sync": "^4.2.0",
+    "rollup": "^2.79.2",
+    "rollup-plugin-copy": "^3.5.0",
+    "typescript": "^5.7.3"
+  },
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
+}