@aglyn/shared-util-fbserver 1.0.0-beta.143 → 1.0.0-beta.145
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/README.md +55 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,3 +1,56 @@
|
|
|
1
|
-
# shared-util-fbserver
|
|
1
|
+
# @aglyn/shared-util-fbserver
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Server-side Firebase Admin bootstrap: one module that initializes the `firebase-admin` default app from environment variables and exposes Firestore and Auth accessors. It is mainly an internal building block of Aglyn's server-side data layer (`@aglyn/tenant-data-admin`); install it directly only if you want the same bootstrap in your own Node process.
|
|
4
|
+
|
|
5
|
+
> Beta. Published from the Aglyn monorepo under the `beta` dist-tag; APIs can change between beta releases.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
npm install @aglyn/shared-util-fbserver@beta
|
|
10
|
+
|
|
11
|
+
Peer dependency: `firebase-admin` (`^14.3.0`).
|
|
12
|
+
|
|
13
|
+
## What's in it
|
|
14
|
+
|
|
15
|
+
A single module, `src/lib/fbserver`, re-exported from the package root:
|
|
16
|
+
|
|
17
|
+
- `fbAdmin` (also the default export) - a small facade over the modular Admin SDK:
|
|
18
|
+
- `fbAdmin.firestore(app?)` returns a Firestore instance; `fbAdmin.firestore.FieldValue` and `fbAdmin.firestore.Timestamp` are the Admin SDK classes.
|
|
19
|
+
- `fbAdmin.auth(app?)` returns the Auth service.
|
|
20
|
+
- `fbAdminApp` - the initialized `App`, or `undefined` when initialization was skipped.
|
|
21
|
+
- `verifyIdToken(idToken)` - verifies a Firebase ID token with revocation checking always on.
|
|
22
|
+
- `firestoreDatabaseId()` - reads `FIRESTORE_DATABASE_ID`; when set, `fbAdmin.firestore()` targets that named database instead of `(default)`.
|
|
23
|
+
|
|
24
|
+
### It initializes on import
|
|
25
|
+
|
|
26
|
+
Importing this package runs the bootstrap. If a Firebase app already exists it is reused. Otherwise the module reads:
|
|
27
|
+
|
|
28
|
+
| Variable | Required | Purpose |
|
|
29
|
+
| -- | -- | -- |
|
|
30
|
+
| `NEXT_PUBLIC_FIREBASE_PROJECT_ID` | yes | project id |
|
|
31
|
+
| `FIREBASE_CLIENT_EMAIL` | yes | service account email |
|
|
32
|
+
| `FIREBASE_PRIVATE_KEY` | yes | service account key; literal `\n` sequences are converted to newlines |
|
|
33
|
+
| `NEXT_PUBLIC_FIREBASE_DATABASE_URL` | no | Realtime Database URL |
|
|
34
|
+
| `FIRESTORE_DATABASE_ID` | no | named Firestore database, read at call time |
|
|
35
|
+
|
|
36
|
+
If any of the three required variables is missing, initialization is skipped silently so that a build step which merely loads the module does not crash. Nothing is initialized in that case, and a later `fbAdmin.firestore()` or `fbAdmin.auth()` call fails unless you initialized a default app yourself.
|
|
37
|
+
|
|
38
|
+
`package.json` lists `./src/lib/fbserver.*` under `sideEffects`. That tells bundlers the import must be kept even when nothing from it appears to be used, because the import itself is what initializes the app. For a consumer it means: this is a server-only module with an import-time effect. Never import it from code that can reach a browser bundle, and expect the app to exist (or be skipped) the moment the module loads.
|
|
39
|
+
|
|
40
|
+
## Usage
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
import fbAdmin, { verifyIdToken } from '@aglyn/shared-util-fbserver'
|
|
44
|
+
|
|
45
|
+
const decoded = await verifyIdToken(idToken)
|
|
46
|
+
const snap = await fbAdmin.firestore().doc(`users/${decoded.uid}`).get()
|
|
47
|
+
const now = fbAdmin.firestore.Timestamp.now()
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## How it fits
|
|
51
|
+
|
|
52
|
+
A `shared` package: generic, with no knowledge of Aglyn's model, and it imports no other Aglyn package. Shared packages may only import other shared packages, and they hold no plugin's domain. In the monorepo it is consumed by `@aglyn/tenant-data-admin`, the Admin SDK data layer.
|
|
53
|
+
|
|
54
|
+
## License
|
|
55
|
+
|
|
56
|
+
Apache-2.0. Source: https://github.com/aglyn/aglyn/tree/main/libs/shared/util/fbserver
|