@forge/object-store 3.0.4-next.1 → 3.1.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 (3) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +50 -0
  3. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,28 @@
1
1
  # @forge/object-store
2
2
 
3
+ ## 3.1.0
4
+
5
+ ### Minor Changes
6
+
7
+ - c1a872c: Add `copy` to create an object copy with independent TTL, overwrite, and CDN bucket options, and `touch` to copy metadata onto the same key to renew TTL. Omitting TTL removes expiry. Both operations share the stored bytes without downloading or re-uploading them.
8
+
9
+ Expose the optional ISO-8601 `expiresAt` timestamp on `ObjectReference`. Objects without expiry omit this field.
10
+
11
+ ### Patch Changes
12
+
13
+ - Updated dependencies [8bb2533]
14
+ - Updated dependencies [e865360]
15
+ - Updated dependencies [950be52]
16
+ - @forge/api@8.5.0
17
+
18
+ ## 3.1.0-next.2
19
+
20
+ ### Minor Changes
21
+
22
+ - c1a872c: Add `copy` to create an object copy with independent TTL, overwrite, and CDN bucket options, and `touch` to copy metadata onto the same key to renew TTL. Omitting TTL removes expiry. Both operations share the stored bytes without downloading or re-uploading them.
23
+
24
+ Expose the optional ISO-8601 `expiresAt` timestamp on `ObjectReference`. Objects without expiry omit this field.
25
+
3
26
  ## 3.0.4-next.1
4
27
 
5
28
  ### Patch Changes
package/README.md CHANGED
@@ -77,3 +77,53 @@ const message = buffer.equals(downloaded)
77
77
 
78
78
  console.log(message);
79
79
  ```
80
+
81
+ ## Copy objects and manage TTL
82
+
83
+ ```typescript
84
+ // Copy within the same installation and bucket, with an independent one-day TTL.
85
+ const copied = await fos.copy({
86
+ sourceKey: 'reports/current.pdf',
87
+ destinationKey: 'reports/archive.pdf',
88
+ ttlSeconds: 86400,
89
+ overwrite: false,
90
+ cdn: false
91
+ });
92
+
93
+ // Reset TTL at the existing key to one day from now.
94
+ const renewed = await fos.touch('reports/current.pdf', { ttlSeconds: 86400 });
95
+
96
+ // Remove the existing expiry and retain the object indefinitely.
97
+ const permanent = await fos.touch('reports/current.pdf');
98
+
99
+ // Select the CDN bucket when touching a CDN object.
100
+ await fos.touch('assets/logo.png', { cdn: true, ttlSeconds: 86400 });
101
+ ```
102
+
103
+ Both methods return `ObjectReference | undefined`: destination metadata on success, or `undefined` when the source does not exist, has expired, or has been deleted. Other API failures use the SDK's existing error handling. Metadata includes an optional `expiresAt` ISO-8601 timestamp, omitted when the object has no expiry.
104
+
105
+ `copy` accepts all fields of the service request:
106
+
107
+ | Field | Required | Behavior |
108
+ | --- | --- | --- |
109
+ | `sourceKey` | Yes | Source object key. |
110
+ | `destinationKey` | Yes | Destination object key. |
111
+ | `ttlSeconds` | No | Positive integer seconds up to `Number.MAX_SAFE_INTEGER`, measured from the copy time. Omit to remove expiry from the destination. |
112
+ | `overwrite` | No | Defaults to `true`. Set to `false` to reject an existing destination. Equal source and destination keys with `overwrite: false` return 400. |
113
+ | `cdn` | No | Defaults to `false`. Selects the same bucket for both keys. |
114
+
115
+ `touch(key, options?)` calls `copy` with equal source and destination keys and `overwrite: true`. `TouchOptions` accepts `ttlSeconds` and `cdn`. Omitting `ttlSeconds`, including when only `cdn` is provided, removes the object's existing expiry. Touch creates a new metadata version and resets its creation timestamp. It cannot restore an expired or deleted object.
116
+
117
+ Copying shares the stored bytes without downloading or uploading them. Copies at different keys have independent expiry and deletion metadata. Keys are passed through unchanged, including empty or whitespace-only strings.
118
+
119
+ The package exports `CopyBody` and `TouchOptions` for typed callers:
120
+
121
+ ```typescript
122
+ import fos, { CopyBody, TouchOptions } from '@forge/object-store';
123
+
124
+ const copyBody: CopyBody = { sourceKey: 'source', destinationKey: 'destination' };
125
+ const touchOptions: TouchOptions = { ttlSeconds: 3600 };
126
+
127
+ await fos.copy(copyBody);
128
+ await fos.touch('source', touchOptions);
129
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@forge/object-store",
3
- "version": "3.0.4-next.1",
3
+ "version": "3.1.0",
4
4
  "description": "Forge Object Store SDK",
5
5
  "author": "Atlassian",
6
6
  "license": "SEE LICENSE IN LICENSE.txt",
@@ -18,7 +18,7 @@
18
18
  "typescript": "5.9.2"
19
19
  },
20
20
  "dependencies": {
21
- "@forge/api": "^8.5.0-next.3"
21
+ "@forge/api": "^8.5.0"
22
22
  },
23
23
  "publishConfig": {
24
24
  "registry": "https://packages.atlassian.com/api/npm/npm-public/"