@vllnt/convex-progression 0.1.0-canary.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/LICENSE +21 -0
  3. package/README.md +144 -0
  4. package/dist/client/index.d.ts +61 -0
  5. package/dist/client/index.d.ts.map +1 -0
  6. package/dist/client/index.js +64 -0
  7. package/dist/client/index.js.map +1 -0
  8. package/dist/client/types.d.ts +20 -0
  9. package/dist/client/types.d.ts.map +1 -0
  10. package/dist/client/types.js +3 -0
  11. package/dist/client/types.js.map +1 -0
  12. package/dist/component/_generated/api.d.ts +40 -0
  13. package/dist/component/_generated/api.d.ts.map +1 -0
  14. package/dist/component/_generated/api.js +31 -0
  15. package/dist/component/_generated/api.js.map +1 -0
  16. package/dist/component/_generated/component.d.ts +82 -0
  17. package/dist/component/_generated/component.d.ts.map +1 -0
  18. package/dist/component/_generated/component.js +11 -0
  19. package/dist/component/_generated/component.js.map +1 -0
  20. package/dist/component/_generated/dataModel.d.ts +46 -0
  21. package/dist/component/_generated/dataModel.d.ts.map +1 -0
  22. package/dist/component/_generated/dataModel.js +11 -0
  23. package/dist/component/_generated/dataModel.js.map +1 -0
  24. package/dist/component/_generated/server.d.ts +133 -0
  25. package/dist/component/_generated/server.d.ts.map +1 -0
  26. package/dist/component/_generated/server.js +80 -0
  27. package/dist/component/_generated/server.js.map +1 -0
  28. package/dist/component/convex.config.d.ts +3 -0
  29. package/dist/component/convex.config.d.ts.map +1 -0
  30. package/dist/component/convex.config.js +4 -0
  31. package/dist/component/convex.config.js.map +1 -0
  32. package/dist/component/mutations.d.ts +43 -0
  33. package/dist/component/mutations.d.ts.map +1 -0
  34. package/dist/component/mutations.js +179 -0
  35. package/dist/component/mutations.js.map +1 -0
  36. package/dist/component/queries.d.ts +14 -0
  37. package/dist/component/queries.d.ts.map +1 -0
  38. package/dist/component/queries.js +45 -0
  39. package/dist/component/queries.js.map +1 -0
  40. package/dist/component/schema.d.ts +32 -0
  41. package/dist/component/schema.d.ts.map +1 -0
  42. package/dist/component/schema.js +21 -0
  43. package/dist/component/schema.js.map +1 -0
  44. package/dist/component/validation.d.ts +4 -0
  45. package/dist/component/validation.d.ts.map +1 -0
  46. package/dist/component/validation.js +22 -0
  47. package/dist/component/validation.js.map +1 -0
  48. package/dist/component/validators.d.ts +52 -0
  49. package/dist/component/validators.d.ts.map +1 -0
  50. package/dist/component/validators.js +20 -0
  51. package/dist/component/validators.js.map +1 -0
  52. package/dist/shared.d.ts +15 -0
  53. package/dist/shared.d.ts.map +1 -0
  54. package/dist/shared.js +36 -0
  55. package/dist/shared.js.map +1 -0
  56. package/docs/API.md +69 -0
  57. package/llms-full.txt +930 -0
  58. package/llms.txt +35 -0
  59. package/package.json +92 -0
  60. package/src/client/index.ts +191 -0
  61. package/src/client/types.ts +23 -0
  62. package/src/component/_generated/api.ts +56 -0
  63. package/src/component/_generated/component.ts +107 -0
  64. package/src/component/_generated/dataModel.ts +60 -0
  65. package/src/component/_generated/server.ts +169 -0
  66. package/src/component/convex.config.ts +5 -0
  67. package/src/component/mutations.ts +205 -0
  68. package/src/component/queries.ts +50 -0
  69. package/src/component/schema.ts +21 -0
  70. package/src/component/validation.ts +30 -0
  71. package/src/component/validators.ts +23 -0
  72. package/src/shared.ts +47 -0
  73. package/src/test.ts +15 -0
package/llms.txt ADDED
@@ -0,0 +1,35 @@
1
+ # @vllnt/convex-progression
2
+
3
+ > XP, levels, and streak windows as a Convex component
4
+
5
+ `@vllnt/convex-progression` is an unpublished candidate Convex component. It targets `convex@^1.45.0`.
6
+ It stores one sandboxed table — `progress` (one row per `(scope, subjectRef, key)`: `xp`, `level`,
7
+ `streak`, `maxStreak`, `lastPeriodKey`). `accrue` adds XP; `level` is the count of host-supplied
8
+ `thresholds` that XP has reached. `recordActivity` takes a host `periodKey` and optional
9
+ `expectedPrevious` (same period leaves the streak unchanged but refreshes level/timestamp; match continues the streak; a gap resets to 1).
10
+ `get` can recompute `level` when the host passes `thresholds`. `eraseSubject` deletes in bounded
11
+ batches without a write fence or completion token. XP is bounded by MAX_SAFE_INTEGER;
12
+ reads validate thresholds too. Award requests are not event-idempotent; hosts must deduplicate
13
+ awards, reject late periods, and fence writes during erase. The host owns auth, `subjectRef`, `key`, `delta`, and `thresholds` (never take those from
14
+ the end-user). Distinct from `@vllnt/convex-wallet` (balances) and `@vllnt/convex-quota` (resetting
15
+ caps).
16
+
17
+ ## Docs
18
+
19
+ - [README](README.md): Project overview, installation, usage examples, architecture
20
+ - [API Reference](docs/API.md): Public class methods, return shapes, input validation
21
+ - [Changelog](CHANGELOG.md): Version history and release notes
22
+ - [Contributing](CONTRIBUTING.md): Development setup, validation commands, release workflow
23
+
24
+ ## Examples
25
+
26
+ - [Example component wrapper](example/convex/example.ts): Host-app wrapper functions
27
+ - [Example tests](example/convex/example.test.ts): Simulated usage coverage with `convex-test` (not a real backend)
28
+
29
+ ## Optional
30
+
31
+ - [AGENTS](AGENTS.md): Canonical agent instructions for this repository
32
+ - [Security Policy](SECURITY.md): Vulnerability reporting policy
33
+ - [Code of Conduct](CODE_OF_CONDUCT.md): Community participation guidelines
34
+ - [License](LICENSE): MIT license
35
+ - [Full source bundle](llms-full.txt): Aggregated README, changelog, API docs, and key source files
package/package.json ADDED
@@ -0,0 +1,92 @@
1
+ {
2
+ "name": "@vllnt/convex-progression",
3
+ "version": "0.1.0-canary.0",
4
+ "description": "XP, levels, and streak windows as a Convex component",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "packageManager": "pnpm@9.15.4",
8
+ "files": [
9
+ "dist",
10
+ "src",
11
+ "!src/**/*.test.ts",
12
+ "docs/API.md",
13
+ "CHANGELOG.md",
14
+ "llms.txt",
15
+ "llms-full.txt"
16
+ ],
17
+ "exports": {
18
+ "./package.json": "./package.json",
19
+ ".": {
20
+ "types": "./dist/client/index.d.ts",
21
+ "default": "./dist/client/index.js"
22
+ },
23
+ "./test": "./src/test.ts",
24
+ "./_generated/component.js": {
25
+ "types": "./dist/component/_generated/component.d.ts"
26
+ },
27
+ "./_generated/component": {
28
+ "types": "./dist/component/_generated/component.d.ts"
29
+ },
30
+ "./convex.config": {
31
+ "types": "./dist/component/convex.config.d.ts",
32
+ "default": "./dist/component/convex.config.js"
33
+ },
34
+ "./convex.config.js": {
35
+ "types": "./dist/component/convex.config.d.ts",
36
+ "default": "./dist/component/convex.config.js"
37
+ }
38
+ },
39
+ "types": "./dist/client/index.d.ts",
40
+ "module": "./dist/client/index.js",
41
+ "scripts": {},
42
+ "peerDependencies": {
43
+ "convex": "^1.45.0"
44
+ },
45
+ "devDependencies": {
46
+ "@edge-runtime/vm": "^5.0.0",
47
+ "@types/node": "^22",
48
+ "@typescript/native": "npm:typescript@7.0.2",
49
+ "@vitest/coverage-v8": "^4.1.11",
50
+ "@vllnt/eslint-config": "2.0.0",
51
+ "@vllnt/typescript": "2.0.0",
52
+ "convex": "^1.45.0",
53
+ "convex-test": "^0.0.56",
54
+ "eslint": "^9.39.5",
55
+ "prettier": "^3.9.6",
56
+ "typescript": "npm:@typescript/typescript6@^6.0.2",
57
+ "vite": "^8.2.2",
58
+ "vitest": "^4.1.11"
59
+ },
60
+ "homepage": "https://github.com/vllnt/convex-progression#readme",
61
+ "bugs": {
62
+ "url": "https://github.com/vllnt/convex-progression/issues"
63
+ },
64
+ "author": {
65
+ "name": "bntvllnt",
66
+ "url": "https://bntvllnt.com"
67
+ },
68
+ "funding": {
69
+ "type": "github",
70
+ "url": "https://github.com/sponsors/bntvllnt"
71
+ },
72
+ "repository": {
73
+ "type": "git",
74
+ "url": "https://github.com/vllnt/convex-progression"
75
+ },
76
+ "engines": {
77
+ "node": ">=20"
78
+ },
79
+ "publishConfig": {
80
+ "access": "public",
81
+ "registry": "https://registry.npmjs.org",
82
+ "tag": "canary"
83
+ },
84
+ "sideEffects": false,
85
+ "keywords": [
86
+ "convex",
87
+ "convex-component",
88
+ "progression",
89
+ "xp",
90
+ "streak"
91
+ ]
92
+ }
@@ -0,0 +1,191 @@
1
+ import type {
2
+ FunctionArgs,
3
+ FunctionReference,
4
+ FunctionReturnType,
5
+ } from "convex/server";
6
+
7
+ import { DEFAULT_SCOPE } from "../shared.js";
8
+
9
+ import type {
10
+ AccrueResult,
11
+ ActivityResult,
12
+ ProgressionOptions,
13
+ ProgressState,
14
+ } from "./types.js";
15
+
16
+ export type ProgressionComponent = {
17
+ mutations: {
18
+ accrue: FunctionReference<
19
+ "mutation",
20
+ "internal",
21
+ {
22
+ delta: number;
23
+ key: string;
24
+ scope: string;
25
+ subjectRef: string;
26
+ thresholds: number[];
27
+ },
28
+ AccrueResult
29
+ >;
30
+ eraseSubject: FunctionReference<
31
+ "mutation",
32
+ "internal",
33
+ { batch?: number; scope: string; subjectRef: string },
34
+ number
35
+ >;
36
+ recordActivity: FunctionReference<
37
+ "mutation",
38
+ "internal",
39
+ {
40
+ expectedPrevious?: string;
41
+ key: string;
42
+ periodKey: string;
43
+ scope: string;
44
+ subjectRef: string;
45
+ thresholds: number[];
46
+ },
47
+ ActivityResult
48
+ >;
49
+ reset: FunctionReference<
50
+ "mutation",
51
+ "internal",
52
+ { key: string; scope: string; subjectRef: string },
53
+ null
54
+ >;
55
+ };
56
+ queries: {
57
+ get: FunctionReference<
58
+ "query",
59
+ "internal",
60
+ {
61
+ key: string;
62
+ scope: string;
63
+ subjectRef: string;
64
+ thresholds?: number[];
65
+ },
66
+ null | ProgressState
67
+ >;
68
+ };
69
+ };
70
+
71
+ type RunQueryCtx = {
72
+ runQuery<TQuery extends FunctionReference<"query", "internal">>(
73
+ reference: TQuery,
74
+ arguments_: FunctionArgs<TQuery>,
75
+ ): Promise<FunctionReturnType<TQuery>>;
76
+ };
77
+
78
+ type RunMutationCtx = {
79
+ runMutation<TMutation extends FunctionReference<"mutation", "internal">>(
80
+ reference: TMutation,
81
+ arguments_: FunctionArgs<TMutation>,
82
+ ): Promise<FunctionReturnType<TMutation>>;
83
+ };
84
+
85
+ export class Progression {
86
+ private readonly defaultScope: string;
87
+
88
+ constructor(
89
+ private readonly component: ProgressionComponent,
90
+ options: ProgressionOptions = {},
91
+ ) {
92
+ this.defaultScope = options.defaultScope ?? DEFAULT_SCOPE;
93
+ }
94
+
95
+ private scopeOf(scope?: string): string {
96
+ return scope ?? this.defaultScope;
97
+ }
98
+
99
+ // Public positional API retained for compatibility.
100
+ // eslint-disable-next-line max-params
101
+ accrue(
102
+ ctx: RunMutationCtx,
103
+ subjectRef: string,
104
+ key: string,
105
+ delta: number,
106
+ thresholds: number[],
107
+ scope?: string,
108
+ ): Promise<AccrueResult> {
109
+ return ctx.runMutation(this.component.mutations.accrue, {
110
+ delta,
111
+ key,
112
+ scope: this.scopeOf(scope),
113
+ subjectRef,
114
+ thresholds,
115
+ });
116
+ }
117
+
118
+ // Public positional API retained for compatibility.
119
+ // eslint-disable-next-line max-params
120
+ recordActivity(
121
+ ctx: RunMutationCtx,
122
+ subjectRef: string,
123
+ key: string,
124
+ periodKey: string,
125
+ thresholds: number[],
126
+ options: { expectedPrevious?: string; scope?: string } = {},
127
+ ): Promise<ActivityResult> {
128
+ return ctx.runMutation(this.component.mutations.recordActivity, {
129
+ expectedPrevious: options.expectedPrevious,
130
+ key,
131
+ periodKey,
132
+ scope: this.scopeOf(options.scope),
133
+ subjectRef,
134
+ thresholds,
135
+ });
136
+ }
137
+
138
+ // Public positional API retained for compatibility.
139
+ // eslint-disable-next-line max-params
140
+ get(
141
+ ctx: RunQueryCtx,
142
+ subjectRef: string,
143
+ key: string,
144
+ scope?: string,
145
+ thresholds?: number[],
146
+ ): Promise<null | ProgressState> {
147
+ return ctx.runQuery(this.component.queries.get, {
148
+ key,
149
+ scope: this.scopeOf(scope),
150
+ subjectRef,
151
+ thresholds,
152
+ });
153
+ }
154
+
155
+ // Public positional API retained for compatibility.
156
+ // eslint-disable-next-line max-params
157
+ reset(
158
+ ctx: RunMutationCtx,
159
+ subjectRef: string,
160
+ key: string,
161
+ scope?: string,
162
+ ): Promise<null> {
163
+ return ctx.runMutation(this.component.mutations.reset, {
164
+ key,
165
+ scope: this.scopeOf(scope),
166
+ subjectRef,
167
+ });
168
+ }
169
+
170
+ // Public positional API retained for compatibility.
171
+ // eslint-disable-next-line max-params
172
+ eraseSubject(
173
+ ctx: RunMutationCtx,
174
+ subjectRef: string,
175
+ scope?: string,
176
+ batch?: number,
177
+ ): Promise<number> {
178
+ return ctx.runMutation(this.component.mutations.eraseSubject, {
179
+ batch,
180
+ scope: this.scopeOf(scope),
181
+ subjectRef,
182
+ });
183
+ }
184
+ }
185
+
186
+ export {
187
+ type AccrueResult,
188
+ type ActivityResult,
189
+ type ProgressionOptions,
190
+ type ProgressState,
191
+ } from "./types.js";
@@ -0,0 +1,23 @@
1
+ /** Public TypeScript surface for the progression client. */
2
+
3
+ export type ProgressState = {
4
+ lastPeriodKey?: string;
5
+ level: number;
6
+ maxStreak: number;
7
+ streak: number;
8
+ updatedAt: number;
9
+ xp: number;
10
+ };
11
+
12
+ export type AccrueResult = {
13
+ leveledUp: boolean;
14
+ previousLevel: number;
15
+ } & ProgressState;
16
+
17
+ export type ActivityResult = {
18
+ streakDelta: number;
19
+ } & ProgressState;
20
+
21
+ export type ProgressionOptions = {
22
+ defaultScope?: string;
23
+ };
@@ -0,0 +1,56 @@
1
+ /* eslint-disable */
2
+ /**
3
+ * Generated `api` utility.
4
+ *
5
+ * THIS CODE IS AUTOMATICALLY GENERATED.
6
+ *
7
+ * To regenerate, run `npx convex dev`.
8
+ * @module
9
+ */
10
+
11
+ import type * as mutations from "../mutations.js";
12
+ import type * as queries from "../queries.js";
13
+ import type * as validation from "../validation.js";
14
+ import type * as validators from "../validators.js";
15
+
16
+ import type {
17
+ ApiFromModules,
18
+ FilterApi,
19
+ FunctionReference,
20
+ } from "convex/server";
21
+ import { anyApi, componentsGeneric } from "convex/server";
22
+
23
+ const fullApi: ApiFromModules<{
24
+ mutations: typeof mutations;
25
+ queries: typeof queries;
26
+ validation: typeof validation;
27
+ validators: typeof validators;
28
+ }> = anyApi as any;
29
+
30
+ /**
31
+ * A utility for referencing Convex functions in your app's public API.
32
+ *
33
+ * Usage:
34
+ * ```js
35
+ * const myFunctionReference = api.myModule.myFunction;
36
+ * ```
37
+ */
38
+ export const api: FilterApi<
39
+ typeof fullApi,
40
+ FunctionReference<any, "public">
41
+ > = anyApi as any;
42
+
43
+ /**
44
+ * A utility for referencing Convex functions in your app's internal API.
45
+ *
46
+ * Usage:
47
+ * ```js
48
+ * const myFunctionReference = internal.myModule.myFunction;
49
+ * ```
50
+ */
51
+ export const internal: FilterApi<
52
+ typeof fullApi,
53
+ FunctionReference<any, "internal">
54
+ > = anyApi as any;
55
+
56
+ export const components = componentsGeneric() as unknown as {};
@@ -0,0 +1,107 @@
1
+ /* eslint-disable */
2
+ /**
3
+ * Generated `ComponentApi` utility.
4
+ *
5
+ * THIS CODE IS AUTOMATICALLY GENERATED.
6
+ *
7
+ * To regenerate, run `npx convex dev`.
8
+ * @module
9
+ */
10
+
11
+ import type { FunctionReference } from "convex/server";
12
+
13
+ /**
14
+ * A utility for referencing a Convex component's exposed API.
15
+ *
16
+ * Useful when expecting a parameter like `components.myComponent`.
17
+ * Usage:
18
+ * ```ts
19
+ * async function myFunction(ctx: QueryCtx, component: ComponentApi) {
20
+ * return ctx.runQuery(component.someFile.someQuery, { ...args });
21
+ * }
22
+ * ```
23
+ */
24
+ export type ComponentApi<Name extends string | undefined = string | undefined> =
25
+ {
26
+ mutations: {
27
+ accrue: FunctionReference<
28
+ "mutation",
29
+ "internal",
30
+ {
31
+ delta: number;
32
+ key: string;
33
+ scope: string;
34
+ subjectRef: string;
35
+ thresholds: Array<number>;
36
+ },
37
+ {
38
+ lastPeriodKey?: string;
39
+ level: number;
40
+ leveledUp: boolean;
41
+ maxStreak: number;
42
+ previousLevel: number;
43
+ streak: number;
44
+ updatedAt: number;
45
+ xp: number;
46
+ },
47
+ Name
48
+ >;
49
+ eraseSubject: FunctionReference<
50
+ "mutation",
51
+ "internal",
52
+ { batch?: number; scope: string; subjectRef: string },
53
+ number,
54
+ Name
55
+ >;
56
+ recordActivity: FunctionReference<
57
+ "mutation",
58
+ "internal",
59
+ {
60
+ expectedPrevious?: string;
61
+ key: string;
62
+ periodKey: string;
63
+ scope: string;
64
+ subjectRef: string;
65
+ thresholds: Array<number>;
66
+ },
67
+ {
68
+ lastPeriodKey?: string;
69
+ level: number;
70
+ maxStreak: number;
71
+ streak: number;
72
+ streakDelta: number;
73
+ updatedAt: number;
74
+ xp: number;
75
+ },
76
+ Name
77
+ >;
78
+ reset: FunctionReference<
79
+ "mutation",
80
+ "internal",
81
+ { key: string; scope: string; subjectRef: string },
82
+ null,
83
+ Name
84
+ >;
85
+ };
86
+ queries: {
87
+ get: FunctionReference<
88
+ "query",
89
+ "internal",
90
+ {
91
+ key: string;
92
+ scope: string;
93
+ subjectRef: string;
94
+ thresholds?: Array<number>;
95
+ },
96
+ null | {
97
+ lastPeriodKey?: string;
98
+ level: number;
99
+ maxStreak: number;
100
+ streak: number;
101
+ updatedAt: number;
102
+ xp: number;
103
+ },
104
+ Name
105
+ >;
106
+ };
107
+ };
@@ -0,0 +1,60 @@
1
+ /* eslint-disable */
2
+ /**
3
+ * Generated data model types.
4
+ *
5
+ * THIS CODE IS AUTOMATICALLY GENERATED.
6
+ *
7
+ * To regenerate, run `npx convex dev`.
8
+ * @module
9
+ */
10
+
11
+ import type {
12
+ DataModelFromSchemaDefinition,
13
+ DocumentByName,
14
+ TableNamesInDataModel,
15
+ SystemTableNames,
16
+ } from "convex/server";
17
+ import type { GenericId } from "convex/values";
18
+ import schema from "../schema.js";
19
+
20
+ /**
21
+ * The names of all of your Convex tables.
22
+ */
23
+ export type TableNames = TableNamesInDataModel<DataModel>;
24
+
25
+ /**
26
+ * The type of a document stored in Convex.
27
+ *
28
+ * @typeParam TableName - A string literal type of the table name (like "users").
29
+ */
30
+ export type Doc<TableName extends TableNames> = DocumentByName<
31
+ DataModel,
32
+ TableName
33
+ >;
34
+
35
+ /**
36
+ * An identifier for a document in Convex.
37
+ *
38
+ * Convex documents are uniquely identified by their `Id`, which is accessible
39
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
40
+ *
41
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
42
+ *
43
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
44
+ * strings when type checking.
45
+ *
46
+ * @typeParam TableName - A string literal type of the table name (like "users").
47
+ */
48
+ export type Id<TableName extends TableNames | SystemTableNames> =
49
+ GenericId<TableName>;
50
+
51
+ /**
52
+ * A type describing your Convex data model.
53
+ *
54
+ * This type includes information about what tables you have, the type of
55
+ * documents stored in those tables, and the indexes defined on them.
56
+ *
57
+ * This type is used to parameterize methods like `queryGeneric` and
58
+ * `mutationGeneric` to make them type-safe.
59
+ */
60
+ export type DataModel = DataModelFromSchemaDefinition<typeof schema>;