Skip to content

Commit d5e98ab

Browse files
eduardoboucaseduardoboucas
committedJun 26, 2023
chore: update README
·
v8.1.2v1.0.0
1 parent 9bf951a commit d5e98ab

File tree

3 files changed

+70
-33
lines changed

3 files changed

+70
-33
lines changed
 

‎README.md

Lines changed: 62 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -7,38 +7,73 @@ A JavaScript client for the Netlify Blob Store.
77

88
## Installation
99

10-
You can install Netlify Blobs via npm:
10+
You can install `@netlify/blobs` via npm:
1111

1212
```shell
1313
npm install @netlify/blobs
1414
```
1515

1616
## Usage
1717

18-
To use the blob store, import the module and create an instance of the `Blobs` class. The constructor accepts an object with the following properties:
18+
To use the blob store, import the module and create an instance of the `Blobs` class. The constructor accepts an object
19+
with the following properties:
1920

20-
| Property | Description | Default Value |
21-
|-----------------|-----------------------------------------------------------|---------------|
22-
| `authentication` | An object containing authentication credentials | N/A |
23-
| `environment` | A string representing the environment | `'production'`|
24-
| `fetcher` | An implementation of a fetch-compatible module | `globalThis.fetch` |
25-
| `siteID` | A string representing the ID of the Netlify site | N/A |
21+
| Property | Description | Required |
22+
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
23+
| `authentication` | An object containing authentication credentials (see [Authentication](#authentication)) | **Yes** |
24+
| `context` | The [deploy context](https://docs.netlify.com/site-deploys/overview/#deploy-contexts) to use (defaults to `production`) | No |
25+
| `fetcher` | An implementation of a [fetch-compatible]https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API module for making HTTP requests (defaults to `globalThis.fetch`) | No |
26+
| `siteID` | The Netlify site ID | **Yes** |
27+
28+
### Authentication
29+
30+
Authentication with the blob storage is done in one of two ways:
31+
32+
- Using a [Netlify API token](https://docs.netlify.com/api/get-started/#authentication)
33+
34+
```javascript
35+
import { Blobs } from '@netlify/blobs'
36+
37+
const store = new Blobs({
38+
authentication: {
39+
token: 'YOUR_NETLIFY_API_TOKEN',
40+
},
41+
siteID: 'YOUR_NETLIFY_SITE_ID',
42+
})
43+
```
44+
45+
- Using a context object injected in Netlify Functions
46+
47+
```javascript
48+
import { Blobs } from '@netlify/blobs'
49+
import type { Handler, HandlerEvent, HandlerContext } from '@netlify/functions'
50+
51+
export const handler: Handler = async (event: HandlerEvent, context: HandlerContext) => {
52+
const store = new Blobs({
53+
authentication: {
54+
contextURL: context.blobs.url,
55+
token: context.blobs.token,
56+
},
57+
siteID: 'YOUR_NETLIFY_SITE_ID',
58+
})
59+
}
60+
```
2661

2762
### Example
2863

2964
```javascript
30-
import { Blobs } from "@netlify/blobs";
65+
import { Blobs } from '@netlify/blobs'
3166

3267
const store = new Blobs({
3368
authentication: {
34-
token: 'YOUR_NETLIFY_AUTH_TOKEN'
69+
token: 'YOUR_NETLIFY_AUTH_TOKEN',
3570
},
36-
siteID: 'YOUR_NETLIFY_SITE_ID'
37-
});
71+
siteID: 'YOUR_NETLIFY_SITE_ID',
72+
})
3873

39-
const item = await store.get("some-key");
74+
const item = await store.get('some-key')
4075

41-
console.log(await item.json());
76+
console.log(await item.json())
4277
```
4378

4479
## API
@@ -47,14 +82,16 @@ console.log(await item.json());
4782

4883
Retrieves an object with the given key.
4984

50-
If an object with the given key is found, a [standard `Response` object](https://developer.mozilla.org/en-US/docs/Web/API/Response) is returned, allowing you to use methods like `.json()`, `.text()`, or `.blob()` to read the underlying value.
85+
If an object with the given key is found, a
86+
[standard `Response` object](https://developer.mozilla.org/en-US/docs/Web/API/Response) is returned, allowing you to use
87+
methods like `.json()`, `.text()`, or `.blob()` to read the underlying value.
5188

5289
Otherwise, `null` is returned.
5390

5491
```javascript
55-
const entry = await blobs.get('some-key');
92+
const entry = await blobs.get('some-key')
5693

57-
console.log(await entry.text());
94+
console.log(await entry.text())
5895
```
5996

6097
### `set(key: string, value: ReadableStream | string | ArrayBuffer | Blob): Promise<void>`
@@ -64,7 +101,7 @@ Creates an object with the given key and value.
64101
If an entry with the given key already exists, its value is overwritten.
65102

66103
```javascript
67-
await blobs.set('some-key', 'This is a string value');
104+
await blobs.set('some-key', 'This is a string value')
68105
```
69106

70107
### `setJSON(key: string, value: any): Promise<void>`
@@ -75,22 +112,24 @@ If an entry with the given key already exists, its value is overwritten.
75112

76113
```javascript
77114
await blobs.setJSON('some-key', {
78-
foo: "bar"
79-
});
115+
foo: 'bar',
116+
})
80117
```
81118

82119
### `delete(key: string): Promise<void>`
83120

84121
Deletes an object with the given key, if one exists.
85122

86123
```javascript
87-
await blobs.delete('my-key');
124+
await blobs.delete('my-key')
88125
```
89126

90127
## Contributing
91128

92-
Contributions are welcome! If you encounter any issues or have suggestions for improvements, please open an issue or submit a pull request on the [GitHub repository](https://github.com/example/netlify-blobs).
129+
Contributions are welcome! If you encounter any issues or have suggestions for improvements, please open an issue or
130+
submit a pull request on the [GitHub repository](https://github.com/example/netlify-blobs).
93131

94132
## License
95133

96-
Netlify Blobs is open-source software licensed under the [MIT license](https://github.com/example/netlify-blobs/blob/main/LICENSE).
134+
Netlify Blobs is open-source software licensed under the
135+
[MIT license](https://github.com/example/netlify-blobs/blob/main/LICENSE).

‎src/main.test.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ describe('With API credentials', () => {
1414
const [url, options] = args
1515
const headers = options?.headers as Record<string, string>
1616

17-
if (url === `https://api.netlify.com/api/v1/sites/${siteID}/blobs/${key}?environment=production`) {
17+
if (url === `https://api.netlify.com/api/v1/sites/${siteID}/blobs/${key}?context=production`) {
1818
const data = JSON.stringify({ url: signedURL })
1919

2020
expect(headers.authorization).toBe(`Bearer ${apiToken}`)

‎src/main.ts

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ interface ContextCredentials {
1313

1414
interface BlobsOptions {
1515
authentication: APICredentials | ContextCredentials
16-
environment?: string
16+
context?: string
1717
fetcher?: typeof globalThis.fetch
1818
siteID: string
1919
}
@@ -28,14 +28,12 @@ type BlobInput = ReadableStream | string | ArrayBuffer | Blob
2828

2929
export class Blobs {
3030
private authentication: APICredentials | ContextCredentials
31-
private cache?: Cache
32-
private cacheDirectory?: string
33-
private environment: string
31+
private context: string
3432
private fetcher: typeof globalThis.fetch
3533
private siteID: string
3634

37-
constructor({ authentication, environment, fetcher, siteID }: BlobsOptions) {
38-
this.environment = environment ?? 'production'
35+
constructor({ authentication, context, fetcher, siteID }: BlobsOptions) {
36+
this.context = context ?? 'production'
3937
this.fetcher = fetcher ?? globalThis.fetch
4038
this.siteID = siteID
4139

@@ -66,11 +64,11 @@ export class Blobs {
6664
authorization: `Bearer ${this.authentication.token}`,
6765
},
6866
method: finalMethod,
69-
url: `${this.authentication.contextURL}/${this.siteID}:${this.environment}:${key}`,
67+
url: `${this.authentication.contextURL}/${this.siteID}:${this.context}:${key}`,
7068
}
7169
}
7270

73-
const apiURL = `${this.authentication.apiURL}/api/v1/sites/${this.siteID}/blobs/${key}?environment=${this.environment}`
71+
const apiURL = `${this.authentication.apiURL}/api/v1/sites/${this.siteID}/blobs/${key}?context=${this.context}`
7472
const headers = { authorization: `Bearer ${this.authentication.token}` }
7573
const res = await this.fetcher(apiURL, { headers, method })
7674
const { url } = await res.json()
@@ -104,7 +102,7 @@ export class Blobs {
104102
return await this.makeStoreRequest(key, HTTPMethod.Delete)
105103
}
106104

107-
async get(key: string) {
105+
async get(key: string, metadata?: Record<string, string>) {
108106
const res = await this.makeStoreRequest(key, HTTPMethod.Get)
109107

110108
if (res.status === 200) {

0 commit comments

Comments
 (0)
Please sign in to comment.