From 2eaff5e77f090dcf5e8af34ce8ea3d2304d7df66 Mon Sep 17 00:00:00 2001 From: Shawn Erquhart Date: Thu, 31 Oct 2024 17:35:23 -0400 Subject: [PATCH] wip --- .github/workflows/node.js.yml | 23 ++ .gitignore | 18 ++ .prettierrc.json | 3 + CONTRIBUTING.md | 50 ++++ LICENSE | 201 +++++++++++++ README.md | 178 ++++++++++++ commonjs.json | 8 + eslint.config.js | 44 +++ esm.json | 8 + example/.gitignore | 16 + example/README.md | 5 + example/convex/README.md | 90 ++++++ example/convex/_generated/api.d.ts | 63 ++++ example/convex/_generated/api.js | 23 ++ example/convex/_generated/dataModel.d.ts | 60 ++++ example/convex/_generated/server.d.ts | 149 ++++++++++ example/convex/_generated/server.js | 90 ++++++ example/convex/convex.config.ts | 7 + example/convex/example.ts | 60 ++++ example/convex/schema.ts | 7 + example/convex/tsconfig.json | 31 ++ example/eslint.config.js | 40 +++ example/index.html | 13 + example/package.json | 32 ++ example/src/App.css | 42 +++ example/src/App.tsx | 23 ++ example/src/index.css | 68 +++++ example/src/main.tsx | 17 ++ example/src/vite-env.d.ts | 1 + example/tsconfig.json | 24 ++ example/vite.config.ts | 10 + node10stubs.mjs | 86 ++++++ package.json | 94 ++++++ src/client/index.ts | 242 +++++++++++++++ src/component/_generated/api.d.ts | 68 +++++ src/component/_generated/api.js | 23 ++ src/component/_generated/dataModel.d.ts | 60 ++++ src/component/_generated/server.d.ts | 149 ++++++++++ src/component/_generated/server.js | 90 ++++++ src/component/convex.config.ts | 3 + src/component/email/index.ts | 55 ++++ .../email/templates/subscriptionEmail.tsx | 143 +++++++++ src/component/init.ts | 130 +++++++++ src/component/lib.ts | 275 ++++++++++++++++++ src/component/polar.ts | 4 + src/component/schema.ts | 77 +++++ src/react/index.ts | 8 + tsconfig.json | 23 ++ 48 files changed, 2934 insertions(+) create mode 100644 .github/workflows/node.js.yml create mode 100644 .gitignore create mode 100644 .prettierrc.json create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 README.md create mode 100644 commonjs.json create mode 100644 eslint.config.js create mode 100644 esm.json create mode 100644 example/.gitignore create mode 100644 example/README.md create mode 100644 example/convex/README.md create mode 100644 example/convex/_generated/api.d.ts create mode 100644 example/convex/_generated/api.js create mode 100644 example/convex/_generated/dataModel.d.ts create mode 100644 example/convex/_generated/server.d.ts create mode 100644 example/convex/_generated/server.js create mode 100644 example/convex/convex.config.ts create mode 100644 example/convex/example.ts create mode 100644 example/convex/schema.ts create mode 100644 example/convex/tsconfig.json create mode 100644 example/eslint.config.js create mode 100644 example/index.html create mode 100644 example/package.json create mode 100644 example/src/App.css create mode 100644 example/src/App.tsx create mode 100644 example/src/index.css create mode 100644 example/src/main.tsx create mode 100644 example/src/vite-env.d.ts create mode 100644 example/tsconfig.json create mode 100644 example/vite.config.ts create mode 100644 node10stubs.mjs create mode 100644 package.json create mode 100644 src/client/index.ts create mode 100644 src/component/_generated/api.d.ts create mode 100644 src/component/_generated/api.js create mode 100644 src/component/_generated/dataModel.d.ts create mode 100644 src/component/_generated/server.d.ts create mode 100644 src/component/_generated/server.js create mode 100644 src/component/convex.config.ts create mode 100644 src/component/email/index.ts create mode 100644 src/component/email/templates/subscriptionEmail.tsx create mode 100644 src/component/init.ts create mode 100644 src/component/lib.ts create mode 100644 src/component/polar.ts create mode 100644 src/component/schema.ts create mode 100644 src/react/index.ts create mode 100644 tsconfig.json diff --git a/.github/workflows/node.js.yml b/.github/workflows/node.js.yml new file mode 100644 index 0000000..587745f --- /dev/null +++ b/.github/workflows/node.js.yml @@ -0,0 +1,23 @@ +name: Run tests +on: + push: + branches: ["main"] + pull_request: + branches: ["main"] +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Use Node.js + uses: actions/setup-node@v4 + with: + cache-dependency-path: | + example/package.json + package.json + node-version: "18.x" + cache: "npm" + - run: npm i + - run: npm ci + - run: cd example && npm i && cd .. + - run: npm test diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..bbf89d3 --- /dev/null +++ b/.gitignore @@ -0,0 +1,18 @@ +.DS_Store +.idea +*.local +*.log +/.vscode/ +/docs/.vitepress/cache +dist +dist-ssr +explorations +node_modules +.eslintcache +# components are libraries! +package-lock.json + +# this is a package-json-redirect stub dir, see https://github.com/andrewbranch/example-subpath-exports-ts-compat?tab=readme-ov-file +react/package.json +# npm pack output +*.tgz diff --git a/.prettierrc.json b/.prettierrc.json new file mode 100644 index 0000000..757fd64 --- /dev/null +++ b/.prettierrc.json @@ -0,0 +1,3 @@ +{ + "trailingComma": "es5" +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..49ef6ee --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,50 @@ +# Developing guide + +## Running locally + +```sh +npm i +cd example +npm i +npx convex dev +``` + +## Testing + +```sh +rm -rf dist/ && npm run build +npm run typecheck +npm run test +cd example +npm run lint +cd .. +``` + +## Deploying + +### Building a one-off package + +```sh +rm -rf dist/ && npm run build +npm pack +``` + +### Deploying a new version + +```sh +# this will change the version and commit it (if you run it in the root directory) +npm version patch +npm publish --dry-run +# sanity check files being included +npm publish +git push --tags +``` + +#### Alpha release + +The same as above, but it requires extra flags so the release is only installed with `@alpha`: + +```sh +npm version prerelease --preid alpha +npm publish --tag alpha +``` diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..c61b663 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + +TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + +2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + +3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + +4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + +5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + +6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + +8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + +END OF TERMS AND CONDITIONS + +APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + +Copyright [yyyy] [name of copyright owner] + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. diff --git a/README.md b/README.md new file mode 100644 index 0000000..7f68161 --- /dev/null +++ b/README.md @@ -0,0 +1,178 @@ +# Convex Component Template + +This is a Convex component, ready to be published on npm. + +To create your own component: + +1. Find and replace "Counter" to your component's Name. +1. Find and replace "counter" to your component's name. +1. Write code in src/component for your component. +1. Write code in src/client for your thick client. +1. Write example usage in example/convex/example.ts. +1. Delete the text in this readme until `---` and flesh out the README. + +It is safe to find & replace "counter" project-wide. + +To develop your component run a dev process in the example project. + +``` +npm i +cd example +npm i +npx convex dev +``` + +Modify the schema and index files in src/component/ to define your component. + +Write a client for using this component in src/client/index.ts. + +If you won't be adding frontend code (e.g. React components) to this +component you can delete the following: + +- "prepack" and "postpack" scripts of package.json +- "./react" exports in package.json +- the "src/react/" directory +- the "node10stubs.mjs" file + +### Component Directory structure + +``` +. +├── README.md documentation of your component +├── package.json component name, version number, other metadata +├── package-lock.json Components are like libraries, package-lock.json +│ is .gitignored and ignored by consumers. +├── src +│   ├── component/ +│   │   ├── _generated/ Files here are generated. +│   │   ├── convex.config.ts Name your component here and use other components +│   │   ├── index.ts Define functions here and in new files in this directory +│   │   └── schema.ts schema specific to this component +│   ├── client/index.ts "Thick" client code goes here. +│   └── react/ Code intended to be used on the frontend goes here. +│ │ Your are free to delete this if this component +│ │ does not provide code. +│   └── index.ts +├── example/ example Convex app that uses this component +│ │ Run 'npx convex dev' from here during development. +│   ├── package.json.ts Thick client code goes here. +│   └── convex/ +│      ├── _generated/ +│      ├── convex.config.ts Imports and uses this component +│      ├── myFunctions.ts Functions that use the component +│      ├── schema.ts Example app schema +│      └── tsconfig.json +│   +├── dist/ Publishing artifacts will be created here. +├── commonjs.json Used during build by TypeScript. +├── esm.json Used during build by TypeScript. +├── node10stubs.mjs Script used during build for compatibility +│ with the Metro bundler used with React Native. +├── eslint.config.mjs Recommended lints for writing a component. +│ Feel free to customize it. +└── tsconfig.json Recommended tsconfig.json for writing a component. + Some settings can be customized, some are required. +``` + +### Structure of a Convex Component + +A Convex components exposes the entry point convex.config.js. The on-disk +location of this file must be a directory containing implementation files. These +files should be compiled to ESM. +The package.json should contain `"type": "module"` and the tsconfig.json should +contain `"moduleResolution": "Bundler"` or `"Node16"` in order to import other +component definitions. + +In addition to convex.config.js, a component typically exposes a client that +wraps communication with the component for use in the Convex +environment is typically exposed as a named export `MyComponentClient` or +`MyComponent` imported from the root package. + +``` +import { MyComponentClient } from "my-convex-component"; +``` + +When frontend code is included it is typically published at a subpath: + +``` +import { helper } from "my-convex-component/react"; +import { FrontendReactComponent } from "my-convex-component/react"; +``` + +Frontend code should be compiled as CommonJS code as well as ESM and make use of +subpackage stubs (see next section). + +If you do include frontend components, prefer peer dependencies to avoid using +more than one version of e.g. React. + +### Support for Node10 module resolution + +The [Metro](https://reactnative.dev/docs/metro) bundler for React Native +requires setting +[`resolver.unstable_enablePackageExports`](https://metrobundler.dev/docs/package-exports/) +in order to import code that lives in `dist/esm/react.js` from a path like +`my-convex-component/react`. + +Authors of Convex component that provide frontend components are encouraged to +support these legacy "Node10-style" module resolution algorithms by generating +stub directories with special pre- and post-pack scripts. + +--- + +# Convex Counter Component + +[![npm version](https://badge.fury.io/js/@convex-dev%2Fcounter.svg)](https://badge.fury.io/js/@convex-dev%2Fcounter) + +**Note: Convex Components are currently in beta** + + + +- [ ] What is some compelling syntax as a hook? +- [ ] Why should you use this component? +- [ ] Links to Stack / other resources? + +Found a bug? Feature request? [File it here](https://github.com/get-convex/counter/issues). + +## Pre-requisite: Convex + +You'll need an existing Convex project to use the component. +Convex is a hosted backend platform, including a database, serverless functions, +and a ton more you can learn about [here](https://docs.convex.dev/get-started). + +Run `npm create convex` or follow any of the [quickstarts](https://docs.convex.dev/home) to set one up. + +## Installation + +Install the component package: + +```ts +npm install @convex-dev/counter +``` + +Create a `convex.config.ts` file in your app's `convex/` folder and install the component by calling `use`: + +```ts +// convex/convex.config.ts +import { defineApp } from "convex/server"; +import counter from "@convex-dev/counter/convex.config"; + +const app = defineApp(); +app.use(counter); + +export default app; +``` + +## Usage + +```ts +import { components } from "./_generated/api"; +import { Counter } from "@convex-dev/counter"; + +const counter = new Counter(components.counter, { + ...options, +}); +``` + +See more example usage in [example.ts](./example/convex/example.ts). + + diff --git a/commonjs.json b/commonjs.json new file mode 100644 index 0000000..29e7d92 --- /dev/null +++ b/commonjs.json @@ -0,0 +1,8 @@ +{ + "extends": "./tsconfig.json", + "include": ["src/**/*"], + "exclude": ["src/**/*.test.*", "../src/package.json"], + "compilerOptions": { + "outDir": "./dist/commonjs" + } +} diff --git a/eslint.config.js b/eslint.config.js new file mode 100644 index 0000000..6f7c313 --- /dev/null +++ b/eslint.config.js @@ -0,0 +1,44 @@ +import globals from "globals"; +import pluginJs from "@eslint/js"; +import tseslint from "typescript-eslint"; + +export default [ + { files: ["src/**/*.{js,mjs,cjs,ts,tsx}"] }, + { + ignores: [ + "dist/**", + "eslint.config.js", + "**/_generated/", + "node10stubs.mjs", + ], + }, + { + languageOptions: { + globals: globals.worker, + parser: tseslint.parser, + + parserOptions: { + project: true, + tsconfigRootDir: ".", + }, + }, + }, + pluginJs.configs.recommended, + ...tseslint.configs.recommended, + { + rules: { + "@typescript-eslint/no-floating-promises": "error", + "eslint-comments/no-unused-disable": "off", + + // allow (_arg: number) => {} and const _foo = 1; + "no-unused-vars": "off", + "@typescript-eslint/no-unused-vars": [ + "warn", + { + argsIgnorePattern: "^_", + varsIgnorePattern: "^_", + }, + ], + }, + }, +]; diff --git a/esm.json b/esm.json new file mode 100644 index 0000000..f984cc5 --- /dev/null +++ b/esm.json @@ -0,0 +1,8 @@ +{ + "extends": "./tsconfig.json", + "include": ["src/**/*"], + "exclude": ["src/**/*.test.*", "../src/package.json"], + "compilerOptions": { + "outDir": "./dist/esm" + } +} diff --git a/example/.gitignore b/example/.gitignore new file mode 100644 index 0000000..983c26f --- /dev/null +++ b/example/.gitignore @@ -0,0 +1,16 @@ +!**/glob-import/dir/node_modules +.DS_Store +.idea +*.cpuprofile +*.local +*.log +/.vscode/ +/docs/.vitepress/cache +dist +dist-ssr +explorations +node_modules +playground-temp +temp +TODOs.md +.eslintcache diff --git a/example/README.md b/example/README.md new file mode 100644 index 0000000..c894719 --- /dev/null +++ b/example/README.md @@ -0,0 +1,5 @@ +# Example app + +Components need an app that uses them in order to run codegen. An example app is also useful +for testing and documentation. + diff --git a/example/convex/README.md b/example/convex/README.md new file mode 100644 index 0000000..4d82e13 --- /dev/null +++ b/example/convex/README.md @@ -0,0 +1,90 @@ +# Welcome to your Convex functions directory! + +Write your Convex functions here. +See https://docs.convex.dev/functions for more. + +A query function that takes two arguments looks like: + +```ts +// functions.js +import { query } from "./_generated/server"; +import { v } from "convex/values"; + +export const myQueryFunction = query({ + // Validators for arguments. + args: { + first: v.number(), + second: v.string(), + }, + + // Function implementation. + handler: async (ctx, args) => { + // Read the database as many times as you need here. + // See https://docs.convex.dev/database/reading-data. + const documents = await ctx.db.query("tablename").collect(); + + // Arguments passed from the client are properties of the args object. + console.log(args.first, args.second); + + // Write arbitrary JavaScript here: filter, aggregate, build derived data, + // remove non-public properties, or create new objects. + return documents; + }, +}); +``` + +Using this query function in a React component looks like: + +```ts +const data = useQuery(api.functions.myQueryFunction, { + first: 10, + second: "hello", +}); +``` + +A mutation function looks like: + +```ts +// functions.js +import { mutation } from "./_generated/server"; +import { v } from "convex/values"; + +export const myMutationFunction = mutation({ + // Validators for arguments. + args: { + first: v.string(), + second: v.string(), + }, + + // Function implementation. + handler: async (ctx, args) => { + // Insert or modify documents in the database here. + // Mutations can also read from the database like queries. + // See https://docs.convex.dev/database/writing-data. + const message = { body: args.first, author: args.second }; + const id = await ctx.db.insert("messages", message); + + // Optionally, return a value from your mutation. + return await ctx.db.get(id); + }, +}); +``` + +Using this mutation function in a React component looks like: + +```ts +const mutation = useMutation(api.functions.myMutationFunction); +function handleButtonPress() { + // fire and forget, the most common way to use mutations + mutation({ first: "Hello!", second: "me" }); + // OR + // use the result once the mutation has completed + mutation({ first: "Hello!", second: "me" }).then((result) => + console.log(result), + ); +} +``` + +Use the Convex CLI to push your functions to a deployment. See everything +the Convex CLI can do by running `npx convex -h` in your project root +directory. To learn more, launch the docs with `npx convex docs`. diff --git a/example/convex/_generated/api.d.ts b/example/convex/_generated/api.d.ts new file mode 100644 index 0000000..08c2f51 --- /dev/null +++ b/example/convex/_generated/api.d.ts @@ -0,0 +1,63 @@ +/* eslint-disable */ +/** + * Generated `api` utility. + * + * THIS CODE IS AUTOMATICALLY GENERATED. + * + * To regenerate, run `npx convex dev`. + * @module + */ + +import type * as example from "../example.js"; + +import type { + ApiFromModules, + FilterApi, + FunctionReference, +} from "convex/server"; +/** + * A utility for referencing Convex functions in your app's API. + * + * Usage: + * ```js + * const myFunctionReference = api.myModule.myFunction; + * ``` + */ +declare const fullApi: ApiFromModules<{ + example: typeof example; +}>; +declare const fullApiWithMounts: typeof fullApi; + +export declare const api: FilterApi< + typeof fullApiWithMounts, + FunctionReference +>; +export declare const internal: FilterApi< + typeof fullApiWithMounts, + FunctionReference +>; + +export declare const components: { + polar: { + lib: { + getOnboardingCheckoutUrl: FunctionReference< + "action", + "internal", + { + polarAccessToken: string; + successUrl: string; + userEmail: string; + userId: string; + }, + any + >; + listPlans: FunctionReference<"query", "internal", {}, any>; + setSubscriptionPending: FunctionReference< + "mutation", + "internal", + any, + any + >; + }; + }; +}; diff --git a/example/convex/_generated/api.js b/example/convex/_generated/api.js new file mode 100644 index 0000000..44bf985 --- /dev/null +++ b/example/convex/_generated/api.js @@ -0,0 +1,23 @@ +/* eslint-disable */ +/** + * Generated `api` utility. + * + * THIS CODE IS AUTOMATICALLY GENERATED. + * + * To regenerate, run `npx convex dev`. + * @module + */ + +import { anyApi, componentsGeneric } from "convex/server"; + +/** + * A utility for referencing Convex functions in your app's API. + * + * Usage: + * ```js + * const myFunctionReference = api.myModule.myFunction; + * ``` + */ +export const api = anyApi; +export const internal = anyApi; +export const components = componentsGeneric(); diff --git a/example/convex/_generated/dataModel.d.ts b/example/convex/_generated/dataModel.d.ts new file mode 100644 index 0000000..8541f31 --- /dev/null +++ b/example/convex/_generated/dataModel.d.ts @@ -0,0 +1,60 @@ +/* eslint-disable */ +/** + * Generated data model types. + * + * THIS CODE IS AUTOMATICALLY GENERATED. + * + * To regenerate, run `npx convex dev`. + * @module + */ + +import type { + DataModelFromSchemaDefinition, + DocumentByName, + TableNamesInDataModel, + SystemTableNames, +} from "convex/server"; +import type { GenericId } from "convex/values"; +import schema from "../schema.js"; + +/** + * The names of all of your Convex tables. + */ +export type TableNames = TableNamesInDataModel; + +/** + * The type of a document stored in Convex. + * + * @typeParam TableName - A string literal type of the table name (like "users"). + */ +export type Doc = DocumentByName< + DataModel, + TableName +>; + +/** + * An identifier for a document in Convex. + * + * Convex documents are uniquely identified by their `Id`, which is accessible + * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids). + * + * Documents can be loaded using `db.get(id)` in query and mutation functions. + * + * IDs are just strings at runtime, but this type can be used to distinguish them from other + * strings when type checking. + * + * @typeParam TableName - A string literal type of the table name (like "users"). + */ +export type Id = + GenericId; + +/** + * A type describing your Convex data model. + * + * This type includes information about what tables you have, the type of + * documents stored in those tables, and the indexes defined on them. + * + * This type is used to parameterize methods like `queryGeneric` and + * `mutationGeneric` to make them type-safe. + */ +export type DataModel = DataModelFromSchemaDefinition; diff --git a/example/convex/_generated/server.d.ts b/example/convex/_generated/server.d.ts new file mode 100644 index 0000000..b5c6828 --- /dev/null +++ b/example/convex/_generated/server.d.ts @@ -0,0 +1,149 @@ +/* eslint-disable */ +/** + * Generated utilities for implementing server-side Convex query and mutation functions. + * + * THIS CODE IS AUTOMATICALLY GENERATED. + * + * To regenerate, run `npx convex dev`. + * @module + */ + +import { + ActionBuilder, + AnyComponents, + HttpActionBuilder, + MutationBuilder, + QueryBuilder, + GenericActionCtx, + GenericMutationCtx, + GenericQueryCtx, + GenericDatabaseReader, + GenericDatabaseWriter, + FunctionReference, +} from "convex/server"; +import type { DataModel } from "./dataModel.js"; + +type GenericCtx = + | GenericActionCtx + | GenericMutationCtx + | GenericQueryCtx; + +/** + * Define a query in this Convex app's public API. + * + * This function will be allowed to read your Convex database and will be accessible from the client. + * + * @param func - The query function. It receives a {@link QueryCtx} as its first argument. + * @returns The wrapped query. Include this as an `export` to name it and make it accessible. + */ +export declare const query: QueryBuilder; + +/** + * Define a query that is only accessible from other Convex functions (but not from the client). + * + * This function will be allowed to read from your Convex database. It will not be accessible from the client. + * + * @param func - The query function. It receives a {@link QueryCtx} as its first argument. + * @returns The wrapped query. Include this as an `export` to name it and make it accessible. + */ +export declare const internalQuery: QueryBuilder; + +/** + * Define a mutation in this Convex app's public API. + * + * This function will be allowed to modify your Convex database and will be accessible from the client. + * + * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument. + * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible. + */ +export declare const mutation: MutationBuilder; + +/** + * Define a mutation that is only accessible from other Convex functions (but not from the client). + * + * This function will be allowed to modify your Convex database. It will not be accessible from the client. + * + * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument. + * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible. + */ +export declare const internalMutation: MutationBuilder; + +/** + * Define an action in this Convex app's public API. + * + * An action is a function which can execute any JavaScript code, including non-deterministic + * code and code with side-effects, like calling third-party services. + * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive. + * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}. + * + * @param func - The action. It receives an {@link ActionCtx} as its first argument. + * @returns The wrapped action. Include this as an `export` to name it and make it accessible. + */ +export declare const action: ActionBuilder; + +/** + * Define an action that is only accessible from other Convex functions (but not from the client). + * + * @param func - The function. It receives an {@link ActionCtx} as its first argument. + * @returns The wrapped function. Include this as an `export` to name it and make it accessible. + */ +export declare const internalAction: ActionBuilder; + +/** + * Define an HTTP action. + * + * This function will be used to respond to HTTP requests received by a Convex + * deployment if the requests matches the path and method where this action + * is routed. Be sure to route your action in `convex/http.js`. + * + * @param func - The function. It receives an {@link ActionCtx} as its first argument. + * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up. + */ +export declare const httpAction: HttpActionBuilder; + +/** + * A set of services for use within Convex query functions. + * + * The query context is passed as the first argument to any Convex query + * function run on the server. + * + * This differs from the {@link MutationCtx} because all of the services are + * read-only. + */ +export type QueryCtx = GenericQueryCtx; + +/** + * A set of services for use within Convex mutation functions. + * + * The mutation context is passed as the first argument to any Convex mutation + * function run on the server. + */ +export type MutationCtx = GenericMutationCtx; + +/** + * A set of services for use within Convex action functions. + * + * The action context is passed as the first argument to any Convex action + * function run on the server. + */ +export type ActionCtx = GenericActionCtx; + +/** + * An interface to read from the database within Convex query functions. + * + * The two entry points are {@link DatabaseReader.get}, which fetches a single + * document by its {@link Id}, or {@link DatabaseReader.query}, which starts + * building a query. + */ +export type DatabaseReader = GenericDatabaseReader; + +/** + * An interface to read from and write to the database within Convex mutation + * functions. + * + * Convex guarantees that all writes within a single mutation are + * executed atomically, so you never have to worry about partial writes leaving + * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control) + * for the guarantees Convex provides your functions. + */ +export type DatabaseWriter = GenericDatabaseWriter; diff --git a/example/convex/_generated/server.js b/example/convex/_generated/server.js new file mode 100644 index 0000000..4a21df4 --- /dev/null +++ b/example/convex/_generated/server.js @@ -0,0 +1,90 @@ +/* eslint-disable */ +/** + * Generated utilities for implementing server-side Convex query and mutation functions. + * + * THIS CODE IS AUTOMATICALLY GENERATED. + * + * To regenerate, run `npx convex dev`. + * @module + */ + +import { + actionGeneric, + httpActionGeneric, + queryGeneric, + mutationGeneric, + internalActionGeneric, + internalMutationGeneric, + internalQueryGeneric, + componentsGeneric, +} from "convex/server"; + +/** + * Define a query in this Convex app's public API. + * + * This function will be allowed to read your Convex database and will be accessible from the client. + * + * @param func - The query function. It receives a {@link QueryCtx} as its first argument. + * @returns The wrapped query. Include this as an `export` to name it and make it accessible. + */ +export const query = queryGeneric; + +/** + * Define a query that is only accessible from other Convex functions (but not from the client). + * + * This function will be allowed to read from your Convex database. It will not be accessible from the client. + * + * @param func - The query function. It receives a {@link QueryCtx} as its first argument. + * @returns The wrapped query. Include this as an `export` to name it and make it accessible. + */ +export const internalQuery = internalQueryGeneric; + +/** + * Define a mutation in this Convex app's public API. + * + * This function will be allowed to modify your Convex database and will be accessible from the client. + * + * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument. + * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible. + */ +export const mutation = mutationGeneric; + +/** + * Define a mutation that is only accessible from other Convex functions (but not from the client). + * + * This function will be allowed to modify your Convex database. It will not be accessible from the client. + * + * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument. + * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible. + */ +export const internalMutation = internalMutationGeneric; + +/** + * Define an action in this Convex app's public API. + * + * An action is a function which can execute any JavaScript code, including non-deterministic + * code and code with side-effects, like calling third-party services. + * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive. + * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}. + * + * @param func - The action. It receives an {@link ActionCtx} as its first argument. + * @returns The wrapped action. Include this as an `export` to name it and make it accessible. + */ +export const action = actionGeneric; + +/** + * Define an action that is only accessible from other Convex functions (but not from the client). + * + * @param func - The function. It receives an {@link ActionCtx} as its first argument. + * @returns The wrapped function. Include this as an `export` to name it and make it accessible. + */ +export const internalAction = internalActionGeneric; + +/** + * Define a Convex HTTP action. + * + * @param func - The function. It receives an {@link ActionCtx} as its first argument, and a `Request` object + * as its second. + * @returns The wrapped endpoint function. Route a URL path to this function in `convex/http.js`. + */ +export const httpAction = httpActionGeneric; diff --git a/example/convex/convex.config.ts b/example/convex/convex.config.ts new file mode 100644 index 0000000..998da50 --- /dev/null +++ b/example/convex/convex.config.ts @@ -0,0 +1,7 @@ +import { defineApp } from "convex/server"; +import polar from "@convex-dev/polar/convex.config"; + +const app = defineApp(); +app.use(polar); + +export default app; diff --git a/example/convex/example.ts b/example/convex/example.ts new file mode 100644 index 0000000..8fa7333 --- /dev/null +++ b/example/convex/example.ts @@ -0,0 +1,60 @@ +import { internalMutation, query, mutation } from "./_generated/server"; +import { components } from "./_generated/api"; +import { Polar } from "@convex-dev/polar"; + +const polar = new Polar(components.polar); + +/* +export const addOne = mutation({ + args: {}, + handler: async (ctx, _args) => { + await numUsers.inc(ctx); + }, +}); + +export const getCount = query({ + args: {}, + handler: async (ctx, _args) => { + return await numUsers.count(ctx); + }, +}); + +export const usingClient = internalMutation({ + args: {}, + handler: async (ctx, _args) => { + await polar.add(ctx, "accomplishments"); + await polar.add(ctx, "beans", 2); + const count = await polar.count(ctx, "beans"); + return count; + }, +}); + +export const usingFunctions = internalMutation({ + args: {}, + handler: async (ctx, _args) => { + await numUsers.inc(ctx); + await numUsers.inc(ctx); + await numUsers.dec(ctx); + return numUsers.count(ctx); + }, +}); + +export const directCall = internalMutation({ + args: {}, + handler: async (ctx, _args) => { + await ctx.runMutation(components.polar.lib.add, { + name: "pennies", + count: 250, + }); + await ctx.runMutation(components.polar.lib.add, { + name: "beans", + count: 3, + shards: 100, + }); + const count = await ctx.runQuery(components.polar.lib.count, { + name: "beans", + }); + return count; + }, +}); +*/ diff --git a/example/convex/schema.ts b/example/convex/schema.ts new file mode 100644 index 0000000..46f2860 --- /dev/null +++ b/example/convex/schema.ts @@ -0,0 +1,7 @@ +import { defineSchema } from "convex/server"; + +export default defineSchema( + { + // Any tables used by the example app go here. + }, +); diff --git a/example/convex/tsconfig.json b/example/convex/tsconfig.json new file mode 100644 index 0000000..b8145fd --- /dev/null +++ b/example/convex/tsconfig.json @@ -0,0 +1,31 @@ +{ + /* This TypeScript project config describes the environment that + * Convex functions run in and is used to typecheck them. + * You can modify it, but some settings required to use Convex. + */ + "compilerOptions": { + /* These settings are not required by Convex and can be modified. */ + "allowJs": true, + "strict": true, + "skipLibCheck": true, + + /* These compiler options are required by Convex */ + "target": "ESNext", + "lib": ["ES2021", "dom", "ESNext.Array", "DOM.Iterable"], + "forceConsistentCasingInFileNames": true, + "allowSyntheticDefaultImports": true, + "module": "ESNext", + "moduleResolution": "Bundler", + "isolatedModules": true, + "noEmit": true, + "jsx": "react-jsx", + + /* This should only be used in this example. Real apps should not attempt + * to compile TypeScript because differences between tsconfig.json files can + * cause the code to be compiled differently. + */ + "customConditions": ["@convex-dev/component-source"] + }, + "include": ["./**/*"], + "exclude": ["./_generated"] +} diff --git a/example/eslint.config.js b/example/eslint.config.js new file mode 100644 index 0000000..f0c101e --- /dev/null +++ b/example/eslint.config.js @@ -0,0 +1,40 @@ +import js from "@eslint/js"; +import globals from "globals"; +import reactHooks from "eslint-plugin-react-hooks"; +import reactRefresh from "eslint-plugin-react-refresh"; +import tseslint from "typescript-eslint"; + +export default tseslint.config( + { ignores: ["dist"] }, + { + extends: [js.configs.recommended, ...tseslint.configs.recommended], + files: ["**/*.{ts,tsx}"], + ignores: ["convex"], + languageOptions: { + ecmaVersion: 2020, + globals: globals.browser, + }, + plugins: { + "react-hooks": reactHooks, + "react-refresh": reactRefresh, + }, + rules: { + ...reactHooks.configs.recommended.rules, + // Allow explicit `any`s + "@typescript-eslint/no-explicit-any": "off", + "react-refresh/only-export-components": [ + "warn", + { allowConstantExport: true }, + ], + + "no-unused-vars": "off", + "@typescript-eslint/no-unused-vars": [ + "warn", + { + argsIgnorePattern: "^_", + varsIgnorePattern: "^_", + }, + ], + }, + } +); diff --git a/example/index.html b/example/index.html new file mode 100644 index 0000000..e4b78ea --- /dev/null +++ b/example/index.html @@ -0,0 +1,13 @@ + + + + + + + Vite + React + TS + + +
+ + + diff --git a/example/package.json b/example/package.json new file mode 100644 index 0000000..b7e6119 --- /dev/null +++ b/example/package.json @@ -0,0 +1,32 @@ +{ + "name": "uses-component", + "private": true, + "type": "module", + "version": "0.0.0", + "scripts": { + "dev": "convex dev --live-component-sources --typecheck-components", + "dev:frontend": "vite", + "logs": "convex logs", + "lint": "tsc -p convex && eslint convex" + }, + "dependencies": { + "@convex-dev/polar": "file:..", + "convex": "file:../node_modules/convex", + "react": "^18.3.1", + "react-dom": "^18.3.1" + }, + "devDependencies": { + "@eslint/eslintrc": "^3.1.0", + "@eslint/js": "^9.9.0", + "@types/react": "^18.3.3", + "@types/react-dom": "^18.3.0", + "@vitejs/plugin-react": "^4.3.1", + "eslint": "^9.9.0", + "eslint-plugin-react-hooks": "^5.1.0-rc.0", + "eslint-plugin-react-refresh": "^0.4.9", + "globals": "^15.9.0", + "typescript": "^5.5.0", + "typescript-eslint": "^8.0.1", + "vite": "^5.4.1" + } +} diff --git a/example/src/App.css b/example/src/App.css new file mode 100644 index 0000000..b9d355d --- /dev/null +++ b/example/src/App.css @@ -0,0 +1,42 @@ +#root { + max-width: 1280px; + margin: 0 auto; + padding: 2rem; + text-align: center; +} + +.logo { + height: 6em; + padding: 1.5em; + will-change: filter; + transition: filter 300ms; +} +.logo:hover { + filter: drop-shadow(0 0 2em #646cffaa); +} +.logo.react:hover { + filter: drop-shadow(0 0 2em #61dafbaa); +} + +@keyframes logo-spin { + from { + transform: rotate(0deg); + } + to { + transform: rotate(360deg); + } +} + +@media (prefers-reduced-motion: no-preference) { + a:nth-of-type(2) .logo { + animation: logo-spin infinite 20s linear; + } +} + +.card { + padding: 2em; +} + +.read-the-docs { + color: #888; +} diff --git a/example/src/App.tsx b/example/src/App.tsx new file mode 100644 index 0000000..e61c8b8 --- /dev/null +++ b/example/src/App.tsx @@ -0,0 +1,23 @@ +import "./App.css"; +import { useMutation, useQuery } from "convex/react"; +import { api } from "../convex/_generated/api"; + +function App() { + const count = useQuery(api.example.getCount); + const addOne = useMutation(api.example.addOne); + + return ( + <> +

Convex Polar Component Example

+
+ +

+ See example/convex/example.ts for all the ways to use + this component +

+
+ + ); +} + +export default App; diff --git a/example/src/index.css b/example/src/index.css new file mode 100644 index 0000000..6119ad9 --- /dev/null +++ b/example/src/index.css @@ -0,0 +1,68 @@ +:root { + font-family: Inter, system-ui, Avenir, Helvetica, Arial, sans-serif; + line-height: 1.5; + font-weight: 400; + + color-scheme: light dark; + color: rgba(255, 255, 255, 0.87); + background-color: #242424; + + font-synthesis: none; + text-rendering: optimizeLegibility; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; +} + +a { + font-weight: 500; + color: #646cff; + text-decoration: inherit; +} +a:hover { + color: #535bf2; +} + +body { + margin: 0; + display: flex; + place-items: center; + min-width: 320px; + min-height: 100vh; +} + +h1 { + font-size: 3.2em; + line-height: 1.1; +} + +button { + border-radius: 8px; + border: 1px solid transparent; + padding: 0.6em 1.2em; + font-size: 1em; + font-weight: 500; + font-family: inherit; + background-color: #1a1a1a; + cursor: pointer; + transition: border-color 0.25s; +} +button:hover { + border-color: #646cff; +} +button:focus, +button:focus-visible { + outline: 4px auto -webkit-focus-ring-color; +} + +@media (prefers-color-scheme: light) { + :root { + color: #213547; + background-color: #ffffff; + } + a:hover { + color: #747bff; + } + button { + background-color: #f9f9f9; + } +} diff --git a/example/src/main.tsx b/example/src/main.tsx new file mode 100644 index 0000000..2669e61 --- /dev/null +++ b/example/src/main.tsx @@ -0,0 +1,17 @@ +import { StrictMode } from "react"; +import { createRoot } from "react-dom/client"; +import { ConvexProvider, ConvexReactClient } from "convex/react"; +import App from "./App.tsx"; +import "./index.css"; + +const address = import.meta.env.VITE_CONVEX_URL; + +const convex = new ConvexReactClient(address); + +createRoot(document.getElementById("root")!).render( + + + + + +); diff --git a/example/src/vite-env.d.ts b/example/src/vite-env.d.ts new file mode 100644 index 0000000..11f02fe --- /dev/null +++ b/example/src/vite-env.d.ts @@ -0,0 +1 @@ +/// diff --git a/example/tsconfig.json b/example/tsconfig.json new file mode 100644 index 0000000..9b5c7dd --- /dev/null +++ b/example/tsconfig.json @@ -0,0 +1,24 @@ +{ + "compilerOptions": { + "target": "ESNext", + "lib": ["DOM", "DOM.Iterable", "ESNext"], + "skipLibCheck": false, + "allowSyntheticDefaultImports": true, + "strict": true, + "forceConsistentCasingInFileNames": true, + "module": "ESNext", + "moduleResolution": "Bundler", + "resolveJsonModule": true, + "isolatedModules": true, + "allowImportingTsExtensions": true, + "noEmit": true, + "jsx": "react-jsx", + + /* This should only be used in this example. Real apps should not attempt + * to compile TypeScript because differences between tsconfig.json files can + * cause the code to be compiled differently. + */ + "customConditions": ["@convex-dev/component-source"] + }, + "include": ["./src", "vite.config.ts"] +} diff --git a/example/vite.config.ts b/example/vite.config.ts new file mode 100644 index 0000000..d5ff574 --- /dev/null +++ b/example/vite.config.ts @@ -0,0 +1,10 @@ +import { defineConfig } from "vite"; +import react from "@vitejs/plugin-react"; + +// https://vitejs.dev/config/ +export default defineConfig({ + plugins: [react()], + resolve: { + conditions: ["@convex-dev/component-source"], + }, +}); diff --git a/node10stubs.mjs b/node10stubs.mjs new file mode 100644 index 0000000..6a76782 --- /dev/null +++ b/node10stubs.mjs @@ -0,0 +1,86 @@ +import fs from "fs/promises"; +import path from "path"; + +async function findPackageJson(directory) { + const packagePath = path.join(directory, "package.json"); + try { + await fs.access(packagePath); + return packagePath; + } catch (error) { + const parentDir = path.dirname(directory); + if (parentDir === directory) { + throw new Error("package.json not found"); + } + return findPackageJson(parentDir); + } +} + +async function processSubPackages(packageJsonPath, exports, cleanup = false) { + const baseDir = path.dirname(packageJsonPath); + + for (const [subDir, _] of Object.entries(exports)) { + // package.json is already right where Node10 resolution would expect it. + if (subDir.endsWith("package.json")) continue; + // No need for Node10 resolution for component.config.ts + if (subDir.endsWith("convex.config.js")) continue; + // . just works with Node10 resolution + if (subDir === ".") continue; + console.log(subDir); + + const newDir = path.join(baseDir, subDir); + const newPackageJsonPath = path.join(newDir, "package.json"); + + if (cleanup) { + try { + await fs.rm(newDir, { recursive: true, force: true }); + } catch (error) { + console.error(`Failed to remove ${newDir}:`, error.message); + } + } else { + const newPackageJson = { + main: `../dist/commonjs/${subDir}/index.js`, + module: `../dist/esm/${subDir}/index.js`, + types: `../dist/commonjs/${subDir}/index.d.ts`, + }; + + await fs.mkdir(newDir, { recursive: true }); + await fs.writeFile( + newPackageJsonPath, + JSON.stringify(newPackageJson, null, 2), + ); + } + } +} + +async function main() { + try { + const isCleanup = process.argv.includes("--cleanup"); + const isAddFiles = process.argv.includes("--addFiles"); + const packageJsonPath = await findPackageJson(process.cwd()); + const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf-8")); + + if (!packageJson.exports) { + throw new Error("exports not found in package.json"); + } + + if (isAddFiles) { + return; + } + + await processSubPackages(packageJsonPath, packageJson.exports, isCleanup); + + if (isCleanup) { + console.log( + "Node10 module resolution compatibility stub directories removed.", + ); + } else { + console.log( + "Node10 module resolution compatibility stub directories created", + ); + } + } catch (error) { + console.error("Error:", error.message); + } +} + +main(); diff --git a/package.json b/package.json new file mode 100644 index 0000000..40efbfc --- /dev/null +++ b/package.json @@ -0,0 +1,94 @@ +{ + "name": "@convex-dev/polar", + "description": "A Polar component for Convex.", + "repository": "github:get-convex/polar", + "homepage": "https://github.com/get-convex/polar#readme", + "bugs": { + "email": "support@convex.dev", + "url": "https://github.com/get-convex/polar/issues" + }, + "version": "0.1.0", + "license": "Apache-2.0", + "keywords": [ + "convex", + "component" + ], + "type": "module", + "scripts": { + "build": "npm run build:esm && npm run build:cjs", + "build:esm": "tsc --project ./esm.json && echo '{\\n \"type\": \"module\"\\n}' > dist/esm/package.json", + "build:cjs": "tsc --project ./commonjs.json && echo '{\\n \"type\": \"commonjs\"\\n}' > dist/commonjs/package.json", + "dev": "cd example; npm run dev", + "typecheck": "tsc --noEmit", + "prepare": "npm run build", + "prepack": "node node10stubs.mjs", + "postpack": "node node10stubs.mjs --cleanup", + "test": "vitest run", + "test:debug": "vitest --inspect-brk --no-file-parallelism", + "test:coverage": "vitest run --coverage --coverage.reporter=text" + }, + "files": [ + "dist", + "src", + "react" + ], + "exports": { + "./package.json": "./package.json", + ".": { + "import": { + "@convex-dev/component-source": "./src/client/index.ts", + "types": "./dist/esm/client/index.d.ts", + "default": "./dist/esm/client/index.js" + }, + "require": { + "@convex-dev/component-source": "./src/client/index.ts", + "types": "./dist/commonjs/client/index.d.ts", + "default": "./dist/commonjs/client/index.js" + } + }, + "./react": { + "import": { + "@convex-dev/component-source": "./src/react/index.ts", + "types": "./dist/esm/react.d.ts", + "default": "./dist/esm/react.js" + }, + "require": { + "@convex-dev/component-source": "./src/react/index.ts", + "types": "./dist/commonjs/react.d.ts", + "default": "./dist/commonjs/react.js" + } + }, + "./convex.config": { + "import": { + "@convex-dev/component-source": "./src/component/convex.config.ts", + "types": "./dist/esm/component/convex.config.d.ts", + "default": "./dist/esm/component/convex.config.js" + } + } + }, + "peerDependencies": { + "convex": "~1.16.5 || ~1.17.0" + }, + "devDependencies": { + "@eslint/js": "^9.9.1", + "@types/node": "^18.17.0", + "@types/react": "^18.3.12", + "convex-test": "^0.0.33", + "eslint": "^9.9.1", + "globals": "^15.9.0", + "prettier": "3.2.5", + "typescript": "~5.0.3", + "typescript-eslint": "^8.4.0", + "vitest": "^2.1.4" + }, + "main": "./dist/commonjs/client/index.js", + "types": "./dist/commonjs/client/index.d.ts", + "module": "./dist/esm/client/index.js", + "dependencies": { + "@convex-dev/auth": "^0.0.74", + "@polar-sh/sdk": "^0.13.5", + "@react-email/components": "0.0.26", + "convex-helpers": "^0.1.63", + "standardwebhooks": "^1.0.0" + } +} diff --git a/src/client/index.ts b/src/client/index.ts new file mode 100644 index 0000000..6d0d250 --- /dev/null +++ b/src/client/index.ts @@ -0,0 +1,242 @@ +import { + Expand, + FunctionReference, + GenericDataModel, + GenericMutationCtx, + GenericQueryCtx, + HttpRouter, +} from "convex/server"; +import { GenericId } from "convex/values"; +import { api } from "../component/_generated/api"; + +import { + type WebhookSubscriptionCreatedPayload, + type WebhookSubscriptionCreatedPayload$Outbound, + WebhookSubscriptionCreatedPayload$inboundSchema as WebhookSubscriptionCreatedPayloadSchema, +} from "@polar-sh/sdk/models/components/webhooksubscriptioncreatedpayload"; +import { + type WebhookSubscriptionUpdatedPayload, + type WebhookSubscriptionUpdatedPayload$Outbound, + WebhookSubscriptionUpdatedPayload$inboundSchema as WebhookSubscriptionUpdatedPayloadSchema, +} from "@polar-sh/sdk/models/components/webhooksubscriptionupdatedpayload"; +import { Webhook } from "standardwebhooks"; +import { internal } from "../component/_generated/api"; +import type { Doc } from "../component/_generated/dataModel"; +import { httpAction, type ActionCtx } from "../component/_generated/server"; +import { + sendSubscriptionErrorEmail, + sendSubscriptionSuccessEmail, +} from "../component/email/templates/subscriptionEmail"; + +const handleUpdateSubscription = async ( + ctx: ActionCtx, + user: Doc<"users">, + subscription: + | WebhookSubscriptionCreatedPayload + | WebhookSubscriptionUpdatedPayload +) => { + const subscriptionItem = subscription.data; + await ctx.runMutation(internal.lib.replaceSubscription, { + userId: user._id, + subscriptionPolarId: subscription.data.id, + input: { + productId: subscriptionItem.productId, + priceId: subscriptionItem.priceId, + interval: subscriptionItem.recurringInterval, + status: subscriptionItem.status, + currency: "usd", + currentPeriodStart: subscriptionItem.currentPeriodStart.getTime(), + currentPeriodEnd: subscriptionItem.currentPeriodEnd?.getTime(), + cancelAtPeriodEnd: subscriptionItem.cancelAtPeriodEnd, + }, + }); +}; + +const handleSubscriptionChange = async ( + ctx: ActionCtx, + event: WebhookSubscriptionCreatedPayload | WebhookSubscriptionUpdatedPayload +) => { + const user = await ctx.runMutation(internal.lib.getsertUser, { + polarId: event.data.userId, + email: event.data.user.email, + }); + if (!user?.email) { + throw new Error("User not found"); + } + + await handleUpdateSubscription(ctx, user, event); + + const freePlan = await ctx.runQuery(internal.lib.getPlanByKey, { + key: "free", + }); + + // Only send email for paid plans + if (event.data.productId !== freePlan?.polarProductId) { + await sendSubscriptionSuccessEmail({ + email: user.email, + subscriptionId: event.data.id, + }); + } + + return new Response(null); +}; + +const handlePolarSubscriptionUpdatedError = async ( + ctx: ActionCtx, + event: WebhookSubscriptionCreatedPayload | WebhookSubscriptionUpdatedPayload +) => { + const subscription = event.data; + + const user = await ctx.runMutation(internal.lib.getsertUser, { + polarId: subscription.userId, + email: subscription.user.email, + }); + if (!user?.email) throw new Error("User not found"); + + const freePlan = await ctx.runQuery(internal.lib.getPlanByKey, { + key: "free", + }); + + // Only send email for paid plans + if (event.data.productId !== freePlan?.polarProductId) { + await sendSubscriptionErrorEmail({ + email: user.email, + subscriptionId: subscription.id, + }); + } + return new Response(null); +}; + +export class Polar { + constructor(public component: UseApi) {} + + registerRoutes(http: HttpRouter) { + http.route({ + path: "/polar/message-status", + method: "POST", + handler: httpAction(async (ctx, request) => { + if (!request.body) { + return new Response(null, { status: 400 }); + } + + const wh = new Webhook(btoa(process.env.POLAR_WEBHOOK_SECRET!)); + const body = await request.text(); + const event = wh.verify( + body, + Object.fromEntries(request.headers.entries()) + ) as + | WebhookSubscriptionCreatedPayload$Outbound + | WebhookSubscriptionUpdatedPayload$Outbound; + + try { + switch (event.type) { + /** + * Occurs when a subscription has been created. + */ + case "subscription.created": { + return handleSubscriptionChange( + ctx, + WebhookSubscriptionCreatedPayloadSchema.parse(event) + ); + } + + /** + * Occurs when a subscription has been updated. + * E.g. when a user upgrades or downgrades their plan. + */ + case "subscription.updated": { + return handleSubscriptionChange( + ctx, + WebhookSubscriptionUpdatedPayloadSchema.parse(event) + ); + } + } + } catch { + switch (event.type) { + case "subscription.created": { + return handlePolarSubscriptionUpdatedError( + ctx, + WebhookSubscriptionCreatedPayloadSchema.parse(event) + ); + } + + case "subscription.updated": { + return handlePolarSubscriptionUpdatedError( + ctx, + WebhookSubscriptionUpdatedPayloadSchema.parse(event) + ); + } + } + } + }), + }); + } + /* + async add( + ctx: RunMutationCtx, + name: Name, + count: number = 1 + ) { + const shards = this.options?.shards?.[name] ?? this.options?.defaultShards; + return ctx.runMutation(this.component.lib.add, { + name, + count, + shards, + }); + } + async count( + ctx: RunQueryCtx, + name: Name + ) { + return ctx.runQuery(this.component.lib.count, { name }); + } + // Another way of exporting functionality + for(name: Name) { + return { + add: async (ctx: RunMutationCtx, count: number = 1) => + this.add(ctx, name, count), + subtract: async (ctx: RunMutationCtx, count: number = 1) => + this.add(ctx, name, -count), + inc: async (ctx: RunMutationCtx) => this.add(ctx, name, 1), + dec: async (ctx: RunMutationCtx) => this.add(ctx, name, -1), + count: async (ctx: RunQueryCtx) => this.count(ctx, name), + }; + } + */ +} + +/* Type utils follow */ + +type RunQueryCtx = { + runQuery: GenericQueryCtx["runQuery"]; +}; +type RunMutationCtx = { + runMutation: GenericMutationCtx["runMutation"]; +}; + +export type OpaqueIds = + T extends GenericId + ? string + : T extends (infer U)[] + ? OpaqueIds[] + : T extends object + ? { [K in keyof T]: OpaqueIds } + : T; + +export type UseApi = Expand<{ + [mod in keyof API]: API[mod] extends FunctionReference< + infer FType, + "public", + infer FArgs, + infer FReturnType, + infer FComponentPath + > + ? FunctionReference< + FType, + "internal", + OpaqueIds, + OpaqueIds, + FComponentPath + > + : UseApi; +}>; diff --git a/src/component/_generated/api.d.ts b/src/component/_generated/api.d.ts new file mode 100644 index 0000000..4fdb657 --- /dev/null +++ b/src/component/_generated/api.d.ts @@ -0,0 +1,68 @@ +/* eslint-disable */ +/** + * Generated `api` utility. + * + * THIS CODE IS AUTOMATICALLY GENERATED. + * + * To regenerate, run `npx convex dev`. + * @module + */ + +import type * as email_index from "../email/index.js"; +import type * as email_templates_subscriptionEmail from "../email/templates/subscriptionEmail.js"; +import type * as init from "../init.js"; +import type * as lib from "../lib.js"; +import type * as polar from "../polar.js"; + +import type { + ApiFromModules, + FilterApi, + FunctionReference, +} from "convex/server"; +/** + * A utility for referencing Convex functions in your app's API. + * + * Usage: + * ```js + * const myFunctionReference = api.myModule.myFunction; + * ``` + */ +declare const fullApi: ApiFromModules<{ + "email/index": typeof email_index; + "email/templates/subscriptionEmail": typeof email_templates_subscriptionEmail; + init: typeof init; + lib: typeof lib; + polar: typeof polar; +}>; +export type Mounts = { + lib: { + getOnboardingCheckoutUrl: FunctionReference< + "action", + "public", + { + polarAccessToken: string; + successUrl: string; + userEmail: string; + userId: string; + }, + any + >; + listPlans: FunctionReference<"query", "public", {}, any>; + setSubscriptionPending: FunctionReference<"mutation", "public", any, any>; + }; +}; +// For now fullApiWithMounts is only fullApi which provides +// jump-to-definition in component client code. +// Use Mounts for the same type without the inference. +declare const fullApiWithMounts: typeof fullApi; + +export declare const api: FilterApi< + typeof fullApiWithMounts, + FunctionReference +>; +export declare const internal: FilterApi< + typeof fullApiWithMounts, + FunctionReference +>; + +export declare const components: {}; diff --git a/src/component/_generated/api.js b/src/component/_generated/api.js new file mode 100644 index 0000000..44bf985 --- /dev/null +++ b/src/component/_generated/api.js @@ -0,0 +1,23 @@ +/* eslint-disable */ +/** + * Generated `api` utility. + * + * THIS CODE IS AUTOMATICALLY GENERATED. + * + * To regenerate, run `npx convex dev`. + * @module + */ + +import { anyApi, componentsGeneric } from "convex/server"; + +/** + * A utility for referencing Convex functions in your app's API. + * + * Usage: + * ```js + * const myFunctionReference = api.myModule.myFunction; + * ``` + */ +export const api = anyApi; +export const internal = anyApi; +export const components = componentsGeneric(); diff --git a/src/component/_generated/dataModel.d.ts b/src/component/_generated/dataModel.d.ts new file mode 100644 index 0000000..8541f31 --- /dev/null +++ b/src/component/_generated/dataModel.d.ts @@ -0,0 +1,60 @@ +/* eslint-disable */ +/** + * Generated data model types. + * + * THIS CODE IS AUTOMATICALLY GENERATED. + * + * To regenerate, run `npx convex dev`. + * @module + */ + +import type { + DataModelFromSchemaDefinition, + DocumentByName, + TableNamesInDataModel, + SystemTableNames, +} from "convex/server"; +import type { GenericId } from "convex/values"; +import schema from "../schema.js"; + +/** + * The names of all of your Convex tables. + */ +export type TableNames = TableNamesInDataModel; + +/** + * The type of a document stored in Convex. + * + * @typeParam TableName - A string literal type of the table name (like "users"). + */ +export type Doc = DocumentByName< + DataModel, + TableName +>; + +/** + * An identifier for a document in Convex. + * + * Convex documents are uniquely identified by their `Id`, which is accessible + * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids). + * + * Documents can be loaded using `db.get(id)` in query and mutation functions. + * + * IDs are just strings at runtime, but this type can be used to distinguish them from other + * strings when type checking. + * + * @typeParam TableName - A string literal type of the table name (like "users"). + */ +export type Id = + GenericId; + +/** + * A type describing your Convex data model. + * + * This type includes information about what tables you have, the type of + * documents stored in those tables, and the indexes defined on them. + * + * This type is used to parameterize methods like `queryGeneric` and + * `mutationGeneric` to make them type-safe. + */ +export type DataModel = DataModelFromSchemaDefinition; diff --git a/src/component/_generated/server.d.ts b/src/component/_generated/server.d.ts new file mode 100644 index 0000000..b5c6828 --- /dev/null +++ b/src/component/_generated/server.d.ts @@ -0,0 +1,149 @@ +/* eslint-disable */ +/** + * Generated utilities for implementing server-side Convex query and mutation functions. + * + * THIS CODE IS AUTOMATICALLY GENERATED. + * + * To regenerate, run `npx convex dev`. + * @module + */ + +import { + ActionBuilder, + AnyComponents, + HttpActionBuilder, + MutationBuilder, + QueryBuilder, + GenericActionCtx, + GenericMutationCtx, + GenericQueryCtx, + GenericDatabaseReader, + GenericDatabaseWriter, + FunctionReference, +} from "convex/server"; +import type { DataModel } from "./dataModel.js"; + +type GenericCtx = + | GenericActionCtx + | GenericMutationCtx + | GenericQueryCtx; + +/** + * Define a query in this Convex app's public API. + * + * This function will be allowed to read your Convex database and will be accessible from the client. + * + * @param func - The query function. It receives a {@link QueryCtx} as its first argument. + * @returns The wrapped query. Include this as an `export` to name it and make it accessible. + */ +export declare const query: QueryBuilder; + +/** + * Define a query that is only accessible from other Convex functions (but not from the client). + * + * This function will be allowed to read from your Convex database. It will not be accessible from the client. + * + * @param func - The query function. It receives a {@link QueryCtx} as its first argument. + * @returns The wrapped query. Include this as an `export` to name it and make it accessible. + */ +export declare const internalQuery: QueryBuilder; + +/** + * Define a mutation in this Convex app's public API. + * + * This function will be allowed to modify your Convex database and will be accessible from the client. + * + * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument. + * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible. + */ +export declare const mutation: MutationBuilder; + +/** + * Define a mutation that is only accessible from other Convex functions (but not from the client). + * + * This function will be allowed to modify your Convex database. It will not be accessible from the client. + * + * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument. + * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible. + */ +export declare const internalMutation: MutationBuilder; + +/** + * Define an action in this Convex app's public API. + * + * An action is a function which can execute any JavaScript code, including non-deterministic + * code and code with side-effects, like calling third-party services. + * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive. + * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}. + * + * @param func - The action. It receives an {@link ActionCtx} as its first argument. + * @returns The wrapped action. Include this as an `export` to name it and make it accessible. + */ +export declare const action: ActionBuilder; + +/** + * Define an action that is only accessible from other Convex functions (but not from the client). + * + * @param func - The function. It receives an {@link ActionCtx} as its first argument. + * @returns The wrapped function. Include this as an `export` to name it and make it accessible. + */ +export declare const internalAction: ActionBuilder; + +/** + * Define an HTTP action. + * + * This function will be used to respond to HTTP requests received by a Convex + * deployment if the requests matches the path and method where this action + * is routed. Be sure to route your action in `convex/http.js`. + * + * @param func - The function. It receives an {@link ActionCtx} as its first argument. + * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up. + */ +export declare const httpAction: HttpActionBuilder; + +/** + * A set of services for use within Convex query functions. + * + * The query context is passed as the first argument to any Convex query + * function run on the server. + * + * This differs from the {@link MutationCtx} because all of the services are + * read-only. + */ +export type QueryCtx = GenericQueryCtx; + +/** + * A set of services for use within Convex mutation functions. + * + * The mutation context is passed as the first argument to any Convex mutation + * function run on the server. + */ +export type MutationCtx = GenericMutationCtx; + +/** + * A set of services for use within Convex action functions. + * + * The action context is passed as the first argument to any Convex action + * function run on the server. + */ +export type ActionCtx = GenericActionCtx; + +/** + * An interface to read from the database within Convex query functions. + * + * The two entry points are {@link DatabaseReader.get}, which fetches a single + * document by its {@link Id}, or {@link DatabaseReader.query}, which starts + * building a query. + */ +export type DatabaseReader = GenericDatabaseReader; + +/** + * An interface to read from and write to the database within Convex mutation + * functions. + * + * Convex guarantees that all writes within a single mutation are + * executed atomically, so you never have to worry about partial writes leaving + * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control) + * for the guarantees Convex provides your functions. + */ +export type DatabaseWriter = GenericDatabaseWriter; diff --git a/src/component/_generated/server.js b/src/component/_generated/server.js new file mode 100644 index 0000000..4a21df4 --- /dev/null +++ b/src/component/_generated/server.js @@ -0,0 +1,90 @@ +/* eslint-disable */ +/** + * Generated utilities for implementing server-side Convex query and mutation functions. + * + * THIS CODE IS AUTOMATICALLY GENERATED. + * + * To regenerate, run `npx convex dev`. + * @module + */ + +import { + actionGeneric, + httpActionGeneric, + queryGeneric, + mutationGeneric, + internalActionGeneric, + internalMutationGeneric, + internalQueryGeneric, + componentsGeneric, +} from "convex/server"; + +/** + * Define a query in this Convex app's public API. + * + * This function will be allowed to read your Convex database and will be accessible from the client. + * + * @param func - The query function. It receives a {@link QueryCtx} as its first argument. + * @returns The wrapped query. Include this as an `export` to name it and make it accessible. + */ +export const query = queryGeneric; + +/** + * Define a query that is only accessible from other Convex functions (but not from the client). + * + * This function will be allowed to read from your Convex database. It will not be accessible from the client. + * + * @param func - The query function. It receives a {@link QueryCtx} as its first argument. + * @returns The wrapped query. Include this as an `export` to name it and make it accessible. + */ +export const internalQuery = internalQueryGeneric; + +/** + * Define a mutation in this Convex app's public API. + * + * This function will be allowed to modify your Convex database and will be accessible from the client. + * + * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument. + * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible. + */ +export const mutation = mutationGeneric; + +/** + * Define a mutation that is only accessible from other Convex functions (but not from the client). + * + * This function will be allowed to modify your Convex database. It will not be accessible from the client. + * + * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument. + * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible. + */ +export const internalMutation = internalMutationGeneric; + +/** + * Define an action in this Convex app's public API. + * + * An action is a function which can execute any JavaScript code, including non-deterministic + * code and code with side-effects, like calling third-party services. + * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive. + * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}. + * + * @param func - The action. It receives an {@link ActionCtx} as its first argument. + * @returns The wrapped action. Include this as an `export` to name it and make it accessible. + */ +export const action = actionGeneric; + +/** + * Define an action that is only accessible from other Convex functions (but not from the client). + * + * @param func - The function. It receives an {@link ActionCtx} as its first argument. + * @returns The wrapped function. Include this as an `export` to name it and make it accessible. + */ +export const internalAction = internalActionGeneric; + +/** + * Define a Convex HTTP action. + * + * @param func - The function. It receives an {@link ActionCtx} as its first argument, and a `Request` object + * as its second. + * @returns The wrapped endpoint function. Route a URL path to this function in `convex/http.js`. + */ +export const httpAction = httpActionGeneric; diff --git a/src/component/convex.config.ts b/src/component/convex.config.ts new file mode 100644 index 0000000..aaa30a5 --- /dev/null +++ b/src/component/convex.config.ts @@ -0,0 +1,3 @@ +import { defineComponent } from "convex/server"; + +export default defineComponent("polar"); diff --git a/src/component/email/index.ts b/src/component/email/index.ts new file mode 100644 index 0000000..ff539b7 --- /dev/null +++ b/src/component/email/index.ts @@ -0,0 +1,55 @@ +import { z } from "zod"; + +const ResendSuccessSchema = z.object({ + id: z.string(), +}); +const ResendErrorSchema = z.union([ + z.object({ + name: z.string(), + message: z.string(), + statusCode: z.number(), + }), + z.object({ + name: z.literal("UnknownError"), + message: z.literal("Unknown Error"), + statusCode: z.literal(500), + cause: z.any(), + }), +]); + +export type SendEmailOptions = { + to: string | string[]; + subject: string; + html: string; + text?: string; +}; + +export async function sendEmail(options: SendEmailOptions) { + const from = + process.env.RESEND_SENDER_EMAIL_AUTH ?? + "Convex SaaS "; + const email = { from, ...options }; + + const response = await fetch("https://api.resend.com/emails", { + method: "POST", + headers: { + Authorization: `Bearer ${process.env.RESEND_API_KEY}`, + "Content-Type": "application/json", + }, + body: JSON.stringify(email), + }); + + const data = await response.json(); + const parsedData = ResendSuccessSchema.safeParse(data); + + if (response.ok && parsedData.success) { + return { status: "success", data: parsedData } as const; + } + const parsedErrorResult = ResendErrorSchema.safeParse(data); + if (parsedErrorResult.success) { + console.error(parsedErrorResult.data); + throw new Error(`Error sending email: ${parsedErrorResult.data.message}`); + } + console.error(data); + throw new Error("Error sending email"); +} diff --git a/src/component/email/templates/subscriptionEmail.tsx b/src/component/email/templates/subscriptionEmail.tsx new file mode 100644 index 0000000..03c85f9 --- /dev/null +++ b/src/component/email/templates/subscriptionEmail.tsx @@ -0,0 +1,143 @@ +import { + Body, + Container, + Head, + Hr, + Html, + Img, + Link, + Preview, + Text, +} from "@react-email/components"; +import { render } from "@react-email/render"; +import { sendEmail } from "../index"; + +type SubscriptionEmailOptions = { + email: string; + subscriptionId: string; +}; + +/** + * Templates. + */ +export function SubscriptionSuccessEmail({ email }: SubscriptionEmailOptions) { + return ( + + + Successfully Subscribed to PRO + + + + + Hello {email}! + + + Your subscription to PRO has been successfully processed. +
+ We hope you enjoy the new features! + + + The domain-name.com{" "} + team. + +
+ + 200 domain-name.com + + + + + ); +} + +export function SubscriptionErrorEmail({ email }: SubscriptionEmailOptions) { + return ( + + + Subscription Issue - Customer Support + + + + + Hello {email}. + + + We were unable to process your subscription to PRO tier. +
+ But don't worry, we'll not charge you anything. + + + The domain-name.com{" "} + team. + +
+ + 200 domain-name.com + + + + + ); +} + +/** + * Renders. + */ +export function renderSubscriptionSuccessEmail(args: SubscriptionEmailOptions) { + return render(); +} + +export function renderSubscriptionErrorEmail(args: SubscriptionEmailOptions) { + return render(); +} + +/** + * Senders. + */ +export async function sendSubscriptionSuccessEmail({ + email, + subscriptionId, +}: SubscriptionEmailOptions) { + const html = await renderSubscriptionSuccessEmail({ email, subscriptionId }); + + await sendEmail({ + to: email, + subject: "Successfully Subscribed to PRO", + html, + }); +} + +export async function sendSubscriptionErrorEmail({ + email, + subscriptionId, +}: SubscriptionEmailOptions) { + const html = await renderSubscriptionErrorEmail({ email, subscriptionId }); + + await sendEmail({ + to: email, + subject: "Subscription Issue - Customer Support", + html, + }); +} diff --git a/src/component/init.ts b/src/component/init.ts new file mode 100644 index 0000000..4a4d4cb --- /dev/null +++ b/src/component/init.ts @@ -0,0 +1,130 @@ +import { Polar } from "@polar-sh/sdk"; +import { asyncMap } from "convex-helpers"; +import { internal } from "./_generated/api"; +import { internalAction, internalMutation } from "./_generated/server"; +import schema, { CURRENCIES, INTERVALS, PlanKey, PLANS } from "./schema"; + +const seedProducts = [ + { + key: PLANS.FREE, + name: "Free", + description: "Some of the things, free forever.", + amountType: "free", + prices: { + [INTERVALS.MONTH]: { + [CURRENCIES.USD]: 0, + }, + }, + }, + { + key: PLANS.PRO, + name: "Pro", + description: "All the things for one low monthly price.", + amountType: "fixed", + prices: { + [INTERVALS.MONTH]: { + [CURRENCIES.USD]: 2000, + }, + [INTERVALS.YEAR]: { + [CURRENCIES.USD]: 20000, + }, + }, + }, +] as const; + +export const insertSeedPlan = internalMutation({ + args: schema.tables.plans.validator, + handler: async (ctx, args) => { + await ctx.db.insert("plans", { + polarProductId: args.polarProductId, + key: args.key, + name: args.name, + description: args.description, + prices: args.prices, + }); + }, +}); + +const seedProductsAction = internalAction({ + args: {}, + handler: async (ctx) => { + /** + * Stripe Products. + */ + const polar = new Polar({ + server: "sandbox", + accessToken: process.env.POLAR_ACCESS_TOKEN, + }); + const products = await polar.products.list({ + organizationId: process.env.POLAR_ORGANIZATION_ID, + isArchived: false, + }); + if (products?.result?.items?.length) { + console.info("🏃‍♂️ Skipping Polar products creation and seeding."); + return; + } + + await asyncMap(seedProducts, async (product) => { + // Create Polar product. + const polarProduct = await polar.products.create({ + organizationId: process.env.POLAR_ORGANIZATION_ID, + name: product.name, + description: product.description, + prices: Object.entries(product.prices).map(([interval, amount]) => ({ + amountType: product.amountType, + priceAmount: amount.usd, + recurringInterval: interval, + })), + }); + const monthPrice = polarProduct.prices.find( + (price) => + price.type === "recurring" && + price.recurringInterval === INTERVALS.MONTH + ); + const yearPrice = polarProduct.prices.find( + (price) => + price.type === "recurring" && + price.recurringInterval === INTERVALS.YEAR + ); + + await ctx.runMutation(internal.init.insertSeedPlan, { + polarProductId: polarProduct.id, + key: product.key as PlanKey, + name: product.name, + description: product.description, + prices: { + ...(!monthPrice + ? {} + : { + month: { + usd: { + polarId: monthPrice?.id, + amount: + monthPrice.amountType === "fixed" + ? monthPrice.priceAmount + : 0, + }, + }, + }), + ...(!yearPrice + ? {} + : { + year: { + usd: { + polarId: yearPrice?.id, + amount: + yearPrice.amountType === "fixed" + ? yearPrice.priceAmount + : 0, + }, + }, + }), + }, + }); + }); + + console.info("📦 Polar Products have been successfully created."); + }, +}); + +export { seedProductsAction as seedProducts }; diff --git a/src/component/lib.ts b/src/component/lib.ts new file mode 100644 index 0000000..9b2e562 --- /dev/null +++ b/src/component/lib.ts @@ -0,0 +1,275 @@ +import { getAuthUserId } from "@convex-dev/auth/server"; +import { Polar } from "@polar-sh/sdk"; +import { v } from "convex/values"; +import { internal } from "./_generated/api"; +import { + action, + internalAction, + internalMutation, + internalQuery, + mutation, + query, +} from "./_generated/server"; +import schema from "./schema"; + +const createCheckout = async ({ + polarAccessToken, + customerEmail, + productPriceId, + successUrl, + subscriptionId, +}: { + polarAccessToken: string; + customerEmail: string; + productPriceId: string; + successUrl: string; + subscriptionId?: string; +}) => { + const polar = new Polar({ + server: "sandbox", + accessToken: polarAccessToken, + }); + const result = await polar.checkouts.create({ + productPriceId, + successUrl, + customerEmail, + subscriptionId, + }); + return result; +}; + +export const getPlanByKey = internalQuery({ + args: { + key: schema.tables.plans.validator.fields.key, + }, + handler: async (ctx, args) => { + return ctx.db + .query("plans") + .withIndex("key", (q) => q.eq("key", args.key)) + .unique(); + }, +}); + +export const getUserSubscription = internalQuery({ + args: { + userId: v.string(), + }, + handler: async (ctx, args) => { + const user = await ctx.db + .query("users") + .withIndex("userId", (q) => q.eq("userId", args.userId)) + .unique(); + if (!user) { + throw new Error("User not found"); + } + const subscription = await ctx.db + .query("subscriptions") + .withIndex("userId", (q) => q.eq("userId", user._id)) + .unique(); + if (!subscription) { + return null; + } + const plan = await ctx.db.get(subscription.planId); + if (!plan) { + throw new Error("Plan not found"); + } + return { + ...subscription, + plan, + }; + }, +}); + +export const getOnboardingCheckoutUrl = action({ + args: { + polarAccessToken: v.string(), + successUrl: v.string(), + userId: v.string(), + userEmail: v.string(), + }, + handler: async (ctx, args) => { + const product = await ctx.runQuery(internal.lib.getPlanByKey, { + key: "free", + }); + const price = product?.prices.month?.usd; + if (!price) { + throw new Error("Price not found"); + } + const checkout = await createCheckout({ + polarAccessToken: args.polarAccessToken, + customerEmail: args.userEmail, + productPriceId: price.polarId, + successUrl: args.successUrl, + }); + return checkout.url; + }, +}); + +export const getProOnboardingCheckoutUrl = internalAction({ + args: { + interval: schema.tables.subscriptions.validator.fields.interval, + polarAccessToken: v.string(), + successUrl: v.string(), + userId: v.string(), + userEmail: v.string(), + }, + handler: async (ctx, args) => { + const product = await ctx.runQuery(internal.lib.getPlanByKey, { + key: "pro", + }); + const price = + args.interval === "month" + ? product?.prices.month?.usd + : product?.prices.year?.usd; + if (!price) { + throw new Error("Price not found"); + } + const subscription = await ctx.runQuery(internal.lib.getUserSubscription, { + userId: args.userId, + }); + const checkout = await createCheckout({ + polarAccessToken: args.polarAccessToken, + customerEmail: args.userEmail, + productPriceId: price.polarId, + successUrl: args.successUrl, + subscriptionId: subscription?.polarId, + }); + return checkout.url; + }, +}); + +export const listPlans = query({ + args: {}, + handler: async (ctx) => { + const userId = await getAuthUserId(ctx); + if (!userId) { + throw new Error("User not found"); + } + const plans = await ctx.db.query("plans").collect(); + return plans.sort((a, b) => a.key.localeCompare(b.key)); + }, +}); + +export const getsertUser = internalMutation({ + args: { + polarId: v.string(), + email: v.string(), + }, + handler: async (ctx, args) => { + const getUser = () => + ctx.db + .query("users") + .withIndex("polarId", (q) => q.eq("polarId", args.polarId)) + .unique(); + const existingUser = await getUser(); + if (!existingUser) { + await ctx.db.insert("users", { + email: args.email, + polarId: args.polarId, + }); + } + const user = existingUser || (await getUser()); + if (!user) { + throw new Error("User not found"); + } + const subscription = await ctx.db + .query("subscriptions") + .withIndex("userId", (q) => q.eq("userId", user._id)) + .unique(); + if (!subscription) { + return user; + } + const plan = await ctx.db.get(subscription.planId); + if (!plan) { + throw new Error("Plan not found"); + } + return { + ...user, + subscription, + plan, + }; + }, +}); + +export const replaceSubscription = internalMutation({ + args: { + userId: v.id("users"), + subscriptionPolarId: v.string(), + input: v.object({ + currency: schema.tables.subscriptions.validator.fields.currency, + productId: v.string(), + priceId: v.string(), + interval: schema.tables.subscriptions.validator.fields.interval, + status: v.string(), + currentPeriodStart: v.number(), + currentPeriodEnd: v.optional(v.number()), + cancelAtPeriodEnd: v.optional(v.boolean()), + }), + }, + handler: async (ctx, args) => { + const subscription = await ctx.db + .query("subscriptions") + .withIndex("userId", (q) => q.eq("userId", args.userId)) + .unique(); + if (subscription) { + await ctx.db.delete(subscription._id); + } + const plan = await ctx.db + .query("plans") + .withIndex("polarProductId", (q) => + q.eq("polarProductId", args.input.productId) + ) + .unique(); + if (!plan) { + throw new Error("Plan not found"); + } + await ctx.db.insert("subscriptions", { + userId: args.userId, + planId: plan._id, + polarId: args.subscriptionPolarId, + polarPriceId: args.input.priceId, + interval: args.input.interval, + status: args.input.status, + currency: args.input.currency, + currentPeriodStart: args.input.currentPeriodStart, + currentPeriodEnd: args.input.currentPeriodEnd, + cancelAtPeriodEnd: args.input.cancelAtPeriodEnd, + }); + const user = await ctx.db.get(args.userId); + if (!user?.polarSubscriptionPendingId) { + return; + } + await ctx.scheduler.cancel(user.polarSubscriptionPendingId); + await ctx.db.patch(args.userId, { + polarSubscriptionPendingId: undefined, + }); + }, +}); + +export const setSubscriptionPending = mutation({ + handler: async (ctx, _args) => { + const userId = await getAuthUserId(ctx); + if (!userId) { + throw new Error("User not found"); + } + const scheduledFunctionId = await ctx.scheduler.runAfter( + 1000 * 120, + internal.lib.unsetSubscriptionPending, + { userId } + ); + await ctx.db.patch(userId, { + polarSubscriptionPendingId: scheduledFunctionId, + }); + }, +}); + +export const unsetSubscriptionPending = internalMutation({ + args: { + userId: v.id("users"), + }, + handler: async (ctx, args) => { + await ctx.db.patch(args.userId, { + polarSubscriptionPendingId: undefined, + }); + }, +}); diff --git a/src/component/polar.ts b/src/component/polar.ts new file mode 100644 index 0000000..70a8a9b --- /dev/null +++ b/src/component/polar.ts @@ -0,0 +1,4 @@ +import { Polar } from "@convex-dev/polar"; +import { components } from "./_generated/api"; + +export const polar = new Polar(components.polar); diff --git a/src/component/schema.ts b/src/component/schema.ts new file mode 100644 index 0000000..6931f4f --- /dev/null +++ b/src/component/schema.ts @@ -0,0 +1,77 @@ +import { defineSchema, defineTable } from "convex/server"; +import { Infer, v } from "convex/values"; + +export const CURRENCIES = { + USD: "usd", + EUR: "eur", +} as const; +export const currencyValidator = v.union( + v.literal(CURRENCIES.USD), + v.literal(CURRENCIES.EUR) +); + +export const INTERVALS = { + MONTH: "month", + YEAR: "year", +} as const; +export const intervalValidator = v.union( + v.literal(INTERVALS.MONTH), + v.literal(INTERVALS.YEAR) +); + +const priceValidator = v.object({ + polarId: v.string(), + amount: v.number(), +}); +const pricesValidator = v.object({ + [CURRENCIES.USD]: v.optional(priceValidator), + [CURRENCIES.EUR]: v.optional(priceValidator), +}); + +export const PLANS = { + FREE: "free", + PRO: "pro", +} as const; +export const planKeyValidator = v.union( + v.literal(PLANS.FREE), + v.literal(PLANS.PRO) +); + +export type PlanKey = Infer; + +export default defineSchema({ + users: defineTable({ + userId: v.optional(v.string()), + polarId: v.string(), + email: v.string(), + polarSubscriptionPendingId: v.optional(v.id("_scheduled_functions")), + }) + .index("userId", ["userId"]) + .index("polarId", ["polarId"]), + plans: defineTable({ + key: planKeyValidator, + polarProductId: v.string(), + name: v.string(), + description: v.string(), + prices: v.object({ + [INTERVALS.MONTH]: v.optional(pricesValidator), + [INTERVALS.YEAR]: v.optional(pricesValidator), + }), + }) + .index("key", ["key"]) + .index("polarProductId", ["polarProductId"]), + subscriptions: defineTable({ + planId: v.id("plans"), + polarId: v.string(), + polarPriceId: v.string(), + currency: currencyValidator, + interval: intervalValidator, + status: v.string(), + currentPeriodStart: v.optional(v.number()), + currentPeriodEnd: v.optional(v.number()), + cancelAtPeriodEnd: v.optional(v.boolean()), + userId: v.id("users"), + }) + .index("userId", ["userId"]) + .index("polarId", ["polarId"]), +}); diff --git a/src/react/index.ts b/src/react/index.ts new file mode 100644 index 0000000..bf4dec2 --- /dev/null +++ b/src/react/index.ts @@ -0,0 +1,8 @@ +// This is where React components go. +if (typeof window === "undefined") { + throw new Error("this is frontend code, but it's running somewhere else!"); +} + +export function subtract(a: number, b: number): number { + return a - b; +} diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..deec8fe --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,23 @@ +{ + "compilerOptions": { + "allowJs": true, + "checkJs": true, + "strict": true, + "jsx": "react-jsx", + + "target": "ESNext", + "lib": ["ES2021", "dom", "DOM.Iterable"], + "forceConsistentCasingInFileNames": true, + "allowSyntheticDefaultImports": true, + "module": "ESNext", + "moduleResolution": "Bundler", + + "isolatedModules": true, + "declaration": true, + "declarationMap": true, + "sourceMap": true, + "outDir": "./dist", + "skipLibCheck": true + }, + "include": ["./src/**/*"] +}