@forge/usage 0.0.0-stage → 0.1.0-next.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.
package/CHANGELOG.md ADDED
@@ -0,0 +1,7 @@
1
+ # @forge/usage
2
+
3
+ ## 0.1.0-next.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 1820780: Added the `@forge/usage` package with `reportUsageCount`, which reports a billable COUNTER usage event for Marketplace usage-based pricing. It accepts `usageCount`, `usageTimestamp` and an optional `user` account ID, and derives the remaining fields from the runtime.
package/LICENSE.txt ADDED
@@ -0,0 +1,7 @@
1
+ Copyright (c) 2026 Atlassian
2
+ Permission is hereby granted to use this software in accordance with the terms
3
+ and conditions outlined in the Atlassian Developer Terms, which can be found
4
+ at the following URL:
5
+ https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
6
+ By using this software, you agree to comply with these terms and conditions.
7
+ If you do not agree with these terms, you are not permitted to use this software.
package/README.md CHANGED
@@ -1,3 +1,22 @@
1
- # Temporary Holding Version
1
+ # @forge/usage
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Library for reporting billable usage from a Forge app, for Marketplace usage-based pricing.
4
+
5
+ ## Usage example
6
+
7
+ ### Reporting counter usage
8
+
9
+ ```typescript
10
+ import { reportUsageCount } from '@forge/usage';
11
+
12
+ await reportUsageCount({
13
+ usageCount: 1,
14
+ usageTimestamp: Date.now(),
15
+ // Optional: Atlassian account ID the usage is attributed to.
16
+ // Defaults to the Atlassian internal system actor.
17
+ user: '712020:00000000-0000-0000-0000-000000000000'
18
+ });
19
+ ```
20
+
21
+ `reportUsageCount` always reports a `COUNTER` metric. The remaining fields of the usage event are derived from the
22
+ app runtime. It throws if the parameters are invalid or the request fails.
package/out/index.d.ts ADDED
@@ -0,0 +1,12 @@
1
+ import type { FetchMethod } from '@forge/api';
2
+ export declare const USAGE_EVENTS_PATH = "/marketplace/metering/v1/usage-events";
3
+ export declare const BILLABLE_ACTION = "api-call";
4
+ export declare const DEFAULT_ACTOR = "ari:cloud:identity::user/atlassian-internal-system";
5
+ export type ReportUsageCountParams = {
6
+ usageCount: number;
7
+ usageTimestamp: number | Date;
8
+ user?: string;
9
+ };
10
+ export declare const createReportUsageCount: (requestAtlassian: FetchMethod) => (params: ReportUsageCountParams) => Promise<void>;
11
+ export declare const reportUsageCount: (params: ReportUsageCountParams) => Promise<void>;
12
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,eAAO,MAAM,iBAAiB,0CAA0C,CAAC;AACzE,eAAO,MAAM,eAAe,aAAa,CAAC;AAC1C,eAAO,MAAM,aAAa,uDAAuD,CAAC;AAKlF,MAAM,MAAM,sBAAsB,GAAG;IAEnC,UAAU,EAAE,MAAM,CAAC;IAEnB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AA4CF,eAAO,MAAM,sBAAsB,GAAI,kBAAkB,WAAW,MAC3B,QAAQ,sBAAsB,KAAG,OAAO,CAAC,IAAI,CA8BrF,CAAC;AAKF,eAAO,MAAM,gBAAgB,WAnCoB,sBAAsB,KAAG,OAAO,CAAC,IAAI,CAmCP,CAAC"}
package/out/index.js ADDED
@@ -0,0 +1,63 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.reportUsageCount = exports.createReportUsageCount = exports.DEFAULT_ACTOR = exports.BILLABLE_ACTION = exports.USAGE_EVENTS_PATH = void 0;
4
+ const crypto_1 = require("crypto");
5
+ const api_1 = require("@forge/api");
6
+ exports.USAGE_EVENTS_PATH = '/marketplace/metering/v1/usage-events';
7
+ exports.BILLABLE_ACTION = 'api-call';
8
+ exports.DEFAULT_ACTOR = 'ari:cloud:identity::user/atlassian-internal-system';
9
+ const COUNTER_METRIC_TYPE = 'COUNTER';
10
+ const MAX_FUTURE_MS = 5 * 60 * 1000;
11
+ const toUserAri = (aaid) => {
12
+ if (typeof aaid !== 'string' || aaid.length === 0 || /[\s/]/.test(aaid)) {
13
+ throw new Error('Invalid usage report: user must be a non-empty Atlassian account ID.');
14
+ }
15
+ return `ari:cloud:identity::user/${aaid}`;
16
+ };
17
+ const validate = ({ usageCount, usageTimestamp, user }) => {
18
+ if (typeof usageCount !== 'number' ||
19
+ !Number.isFinite(usageCount) ||
20
+ !Number.isInteger(usageCount) ||
21
+ usageCount <= 0) {
22
+ throw new Error('Invalid usage report: usageCount must be an integer greater than 0.');
23
+ }
24
+ const timestamp = usageTimestamp instanceof Date ? usageTimestamp.getTime() : usageTimestamp;
25
+ if (typeof timestamp !== 'number' || !Number.isInteger(timestamp) || timestamp <= 0) {
26
+ throw new Error('Invalid usage report: usageTimestamp must be a valid epoch milliseconds timestamp.');
27
+ }
28
+ const now = Date.now();
29
+ if (timestamp > now + MAX_FUTURE_MS) {
30
+ throw new Error('Invalid usage report: usageTimestamp must not be in the future.');
31
+ }
32
+ return { timestamp, actor: user !== undefined ? toUserAri(user) : exports.DEFAULT_ACTOR };
33
+ };
34
+ const createReportUsageCount = (requestAtlassian) => {
35
+ return async function reportUsageCount(params) {
36
+ const { timestamp: usageTimestamp, actor } = validate(params);
37
+ const { contextAri } = (0, api_1.__getRuntime)();
38
+ const dimensions = [
39
+ { id: 'billableAction', value: exports.BILLABLE_ACTION },
40
+ { id: 'actor', value: actor },
41
+ { id: 'installationContext', value: contextAri },
42
+ { id: 'sandboxAppChargeable', value: 'false' }
43
+ ];
44
+ const payload = {
45
+ usageUniqueId: (0, crypto_1.randomUUID)(),
46
+ metricType: COUNTER_METRIC_TYPE,
47
+ usageCount: params.usageCount,
48
+ usageTimestamp,
49
+ applicableExemptionId: null,
50
+ dimensions
51
+ };
52
+ const response = await requestAtlassian(exports.USAGE_EVENTS_PATH, {
53
+ method: 'POST',
54
+ headers: { 'content-type': 'application/json' },
55
+ body: JSON.stringify(payload)
56
+ });
57
+ if (!response.ok) {
58
+ throw new Error(`Failed to report usage: ${response.status} ${response.statusText}.`);
59
+ }
60
+ };
61
+ };
62
+ exports.createReportUsageCount = createReportUsageCount;
63
+ exports.reportUsageCount = (0, exports.createReportUsageCount)(api_1.__requestAtlassianAsApp);
package/package.json CHANGED
@@ -1,6 +1,32 @@
1
1
  {
2
2
  "name": "@forge/usage",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0-next.0",
4
+ "description": "Forge Usage SDK",
5
+ "main": "out/index.js",
6
+ "types": "out/index.d.ts",
7
+ "scripts": {
8
+ "build": "yarn run clean && yarn run compile",
9
+ "clean": "rm -rf ./out && rm -f tsconfig.tsbuildinfo",
10
+ "compile": "tsc -b -v"
11
+ },
12
+ "dependencies": {
13
+ "@forge/api": "^8.3.1-next.0"
14
+ },
15
+ "devDependencies": {
16
+ "@types/node": "20.19.1",
17
+ "typescript": "5.9.2"
18
+ },
19
+ "author": "Atlassian",
20
+ "license": "SEE LICENSE IN LICENSE.txt",
21
+ "publishConfig": {
22
+ "registry": "https://packages.atlassian.com/api/npm/npm-public/"
23
+ },
24
+ "peerDependencies": {
25
+ "typescript": ">=5.0.0"
26
+ },
27
+ "peerDependenciesMeta": {
28
+ "typescript": {
29
+ "optional": true
30
+ }
31
+ }
32
+ }