Merge pull request #44 from xmtp/dj/screen-effect

Screen Effect Codec

experimental/content-type-screen-effect/.eslintrc.cjs

@@ -0,0 +1,10 @@
+module.exports = {
+  root: true,
+  extends: ["custom"],
+  parserOptions: {
+    project: "./tsconfig.eslint.json",
+  },
+  rules: {
+    "class-methods-use-this": "off",
+  },
+};

experimental/content-type-screen-effect/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 XMTP developers (xmtp.org)
+
+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.

experimental/content-type-screen-effect/README.md

@@ -0,0 +1,92 @@
+# Screen effect content type
+
+This experimental package provides a content type to support adding screen effects to messages.
+
+## What’s a screen effect?
+
+A screen effect is something that happens on a particular trigger, such as sending balloons along with a happy birthday message or sending snowflakes to accompany a holiday message.
+
+## Why screen effects?
+
+Providing screen effects can be a way to surprise and delight an app's users, by presenting them with an unexpected visual effect.
+
+## Install the package
+
+```bash
+# npm
+npm i @xmtp/experimental-content-type-screen-effect
+
+# yarn
+yarn add @xmtp/experimental-content-type-screen-effect
+
+# pnpm
+pnpm i @xmtp/experimental-content-type-screen-effect
+```
+
+## Create a screen effect
+
+Screen effects are represented as objects with the following keys:
+
+- `messageId`: The message id for the message that the screen effect is being sent with
+- `effectType`: The type of effect (currently `SNOW` or `RAIN`, feel free to add additional effects via a PR)
+
+```tsx
+const screenEffect: ScreenEffect = {
+  reference: someMessageID,
+  effectType: "SNOW",
+};
+```
+
+## Send a screen effect
+
+Now that you have a screen effect, you can send it:
+
+```tsx
+await conversation.messages.send(screenEffect, {
+  contentType: ContentTypeScreenEffect,
+});
+```
+
+> **Note**  
+> `contentFallback` text is provided by the codec and is set to undefined, ensuring that clients that _don't_ support this content type are not required to render anything in their app.
+
+## Receive a screen effect
+
+Now that you can send a screen effect, you need a way to receive it. For example:
+
+```tsx
+// Assume `loadLastMessage` is a thing you have
+const message: DecodedMessage = await loadLastMessage();
+
+if (message.contentType.sameAs(ContentTypeScreenEffect)) {
+  // We've got a screen effect.
+  const screenEffect: ScreenEffect = message.content;
+}
+```
+
+## Display the screen effect
+
+Generally, screen effects sent with snow or rain are displayed as a visual effect. For example, a snow effect might be displayed as snow falling down the page for a short period of time.
+
+It is important to note that these are not intended to be displayed every time a message is loaded; for that reason, apps using screen effects must track the effects that have already been run so as to not re-run effects on every page refresh.
+
+## Developing
+
+Run `yarn dev` to build the content type and watch for changes, which will trigger a rebuild.
+
+## Testing
+
+Before running unit tests, start the required Docker container at the root of this repository. For more info, see [Running tests](../../README.md#running-tests).
+
+## Useful commands
+
+- `yarn build`: Builds the content type
+- `yarn clean`: Removes `node_modules`, `dist`, and `.turbo` folders
+- `yarn dev`: Builds the content type and watches for changes, which will trigger a rebuild
+- `yarn format`: Runs prettier format and write changes
+- `yarn format:check`: Runs prettier format check
+- `yarn lint`: Runs ESLint
+- `yarn test:setup`: Starts a necessary docker container for testing
+- `yarn test:teardown`: Stops docker container for testing
+- `yarn test`: Runs all unit tests
+- `yarn typecheck`: Runs `tsc`

experimental/content-type-screen-effect/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@xmtp/experimental-content-type-screen-effect",
+  "version": "1.0.0",
+  "description": "An experimental content type to support screen effects accompanying messages",
+  "author": "XMTP Labs <[email protected]>",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "browser": "dist/web/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/web/index.js",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "[email protected]:xmtp/xmtp-js-content-types.git",
+    "directory": "experimental/content-type-screen-effect"
+  },
+  "homepage": "https://github.com/xmtp/xmtp-js-content-types",
+  "bugs": {
+    "url": "https://github.com/xmtp/xmtp-js-content-types/issues"
+  },
+  "keywords": [
+    "xmtp",
+    "messaging",
+    "web3",
+    "js",
+    "ts",
+    "javascript",
+    "typescript",
+    "content-types"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 3 chrome versions",
+      "last 3 firefox versions",
+      "last 3 safari versions"
+    ]
+  },
+  "scripts": {
+    "build:node": "tsup",
+    "build:web": "tsup --platform browser --target esnext",
+    "build": "yarn clean:build && yarn build:node && yarn build:web",
+    "clean:build": "rimraf dist",
+    "clean": "rimraf .turbo node_modules && yarn clean:build",
+    "dev": "tsup --watch",
+    "format:base": "prettier --ignore-path ../../.gitignore",
+    "format:check": "yarn format:base -c .",
+    "format": "yarn format:base -w .",
+    "generate:types": "tsup --dts-only",
+    "lint": "eslint . --ignore-path ../../.gitignore",
+    "test:jsdom": "NODE_TLS_REJECT_UNAUTHORIZED=0 vitest run --environment jsdom",
+    "test:node": "NODE_TLS_REJECT_UNAUTHORIZED=0 vitest run --environment node",
+    "test": "yarn test:node && yarn test:jsdom",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@xmtp/xmtp-js": "^11.1.2"
+  },
+  "devDependencies": {
+    "@types/node": "^18.14.2",
+    "buffer": "^6.0.3",
+    "esbuild": "^0.18.2",
+    "esbuild-plugin-external-global": "^1.0.1",
+    "eslint": "^8.43.0",
+    "eslint-config-custom": "workspace:*",
+    "ethers": "^6.0.8",
+    "jsdom": "^22.1.0",
+    "prettier": "^2.8.8",
+    "rimraf": "^5.0.1",
+    "tsup": "^7.0.0",
+    "typescript": "^5.1.3",
+    "vite": "^4.3.9",
+    "vitest": "^0.32.2"
+  },
+  "peerDependencies": {
+    "@xmtp/xmtp-js": "^11.1.1"
+  }
+}

experimental/content-type-screen-effect/src/ScreenEffect.test.ts

@@ -0,0 +1,61 @@
+import { Wallet } from "ethers";
+import { Client } from "@xmtp/xmtp-js";
+import {
+  ContentTypeScreenEffect,
+  EffectType,
+  ScreenEffectCodec,
+} from "./ScreenEffect";
+import type { ScreenEffect } from "./ScreenEffect";
+
+describe("ScreenEffectContentType", () => {
+  it("has the right content type", () => {
+    expect(ContentTypeScreenEffect.authorityId).toBe("xmtp.org");
+    expect(ContentTypeScreenEffect.typeId).toBe("screenEffect");
+    expect(ContentTypeScreenEffect.versionMajor).toBe(1);
+    expect(ContentTypeScreenEffect.versionMinor).toBe(0);
+  });
+
+  it("can send a screen effect", async () => {
+    const aliceWallet = Wallet.createRandom();
+    const aliceClient = await Client.create(aliceWallet, {
+      codecs: [new ScreenEffectCodec()],
+      env: "local",
+    });
+    await aliceClient.publishUserContact();
+
+    const bobWallet = Wallet.createRandom();
+    const bobClient = await Client.create(bobWallet, {
+      codecs: [new ScreenEffectCodec()],
+      env: "local",
+    });
+    await bobClient.publishUserContact();
+
+    const conversation = await aliceClient.conversations.newConversation(
+      bobWallet.address,
+    );
+
+    const originalMessage = await conversation.send("test");
+
+    const screenEffect: ScreenEffect = {
+      messageId: originalMessage.id,
+      effectType: EffectType.SNOW,
+    };
+
+    await conversation.send(screenEffect, {
+      contentType: ContentTypeScreenEffect,
+    });
+
+    const bobConversation = await bobClient.conversations.newConversation(
+      aliceWallet.address,
+    );
+    const messages = await bobConversation.messages();
+
+    expect(messages.length).toBe(2);
+
+    const screenEffectMessage = messages[1];
+    const messageContent = screenEffectMessage.content as ScreenEffect;
+
+    expect(messageContent.messageId).toBe(originalMessage.id);
+    expect(messageContent.effectType).toBe(EffectType.SNOW);
+  });
+});

experimental/content-type-screen-effect/src/ScreenEffect.ts

@@ -0,0 +1,58 @@
+import { ContentTypeId } from "@xmtp/xmtp-js";
+import type { ContentCodec, EncodedContent } from "@xmtp/xmtp-js";
+
+export enum EffectType {
+  SNOW = "SNOW",
+  RAIN = "RAIN",
+}
+
+export const ContentTypeScreenEffect = new ContentTypeId({
+  authorityId: "xmtp.org",
+  typeId: "screenEffect",
+  versionMajor: 1,
+  versionMinor: 0,
+});
+
+export type ScreenEffect = {
+  messageId: string;
+  effectType: EffectType;
+};
+
+export type ScreenEffectParameters = Pick<
+  ScreenEffect,
+  "messageId" | "effectType"
+>;
+
+export class ScreenEffectCodec
+  implements ContentCodec<ScreenEffect | undefined>
+{
+  get contentType(): ContentTypeId {
+    return ContentTypeScreenEffect;
+  }
+
+  encode(content: ScreenEffect): EncodedContent<ScreenEffectParameters> {
+    return {
+      type: ContentTypeScreenEffect,
+      parameters: {
+        messageId: content.messageId,
+        effectType: content.effectType,
+      },
+      content: new Uint8Array(),
+    };
+  }
+
+  decode(
+    content: EncodedContent<ScreenEffectParameters>,
+  ): ScreenEffect | undefined {
+    const { messageId, effectType } = content.parameters;
+
+    return {
+      messageId,
+      effectType,
+    };
+  }
+
+  fallback() {
+    return undefined;
+  }
+}

experimental/content-type-screen-effect/src/index.ts

@@ -0,0 +1,2 @@
+export { ScreenEffectCodec, ContentTypeScreenEffect } from "./ScreenEffect";
+export type { ScreenEffect } from "./ScreenEffect";

experimental/content-type-screen-effect/tsconfig.eslint.json

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "include": [".", ".eslintrc.cjs"],
+  "exclude": ["dist", "node_modules"]
+}

experimental/content-type-screen-effect/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "tsconfig/build.json",
+  "include": ["."],
+  "exclude": ["dist", "node_modules"]
+}

experimental/content-type-screen-effect/tsup.config.ts

@@ -0,0 +1,35 @@
+import { defineConfig } from "tsup";
+import externalGlobal from "esbuild-plugin-external-global";
+import type { Plugin } from "esbuild";
+
+export default defineConfig((options) => {
+  const esbuildPlugins: Plugin[] = [];
+
+  // for the browser bundle, replace `crypto` import with an object that
+  // returns the browser's built-in crypto library
+  if (options.platform === "browser") {
+    esbuildPlugins.push(
+      externalGlobal.externalGlobalPlugin({
+        crypto: "{ webcrypto: window.crypto }",
+      }),
+    );
+  }
+
+  return {
+    entry: options.entry ?? ["src/index.ts"],
+    outDir:
+      options.outDir ?? (options.platform === "browser" ? "dist/web" : "dist"),
+    splitting: false,
+    sourcemap: true,
+    treeshake: true,
+    clean: true,
+    bundle: true,
+    platform: options.platform ?? "node",
+    minify: options.platform === "browser",
+    dts: options.platform !== "browser",
+    format:
+      options.format ??
+      (options.platform === "browser" ? ["esm"] : ["esm", "cjs"]),
+    esbuildPlugins,
+  };
+});