@seedprotocol/publish 0.7.3 → 0.7.4-next.784.g879c6a3

package/README.md

@@ -107,6 +107,81 @@ function App() {
 
 You can optionally pass `queryClient` or `queryClientRef` to customize the Seed QueryClient.
 
+### Who pays
+
+A publish costs EVM gas (attestations, schema registration) and Arweave storage. Who pays follows
+from the sender your config selects:
+
+| Sender | Selected by | Gas |
+|---|---|---|
+| Thirdweb managed account | `useModularExecutor: true` | sponsored by Thirdweb unless `thirdweb.sponsorGas: false` |
+| Permissionless EIP-7702 | `bundlerUrl` (Recipe 2) | sponsored by `paymasterUrl`, else the bundler |
+| Connected wallet | neither | the user's ETH |
+
+Storage goes through the upload API at `uploadApiBaseUrl`, and its operator pays: directly on the
+bundler path, and on the L1 path by reimbursing the user's Arweave key before the upload.
+
+To state the intent instead, set `payment`. It fills in those settings' defaults, and `initPublish`
+throws `PublishPaymentConfigError` when a setting contradicts it:
+
+```typescript
+initPublish({
+  // ...
+  bundlerUrl: import.meta.env.VITE_BUNDLER_URL,
+  payment: { gas: 'user', storage: 'operator' }, // EIP-7702 sender without a paymaster
+})
+```
+
+`resolvePublishPayment(getPublishConfig())` returns the resolved sender and payers; `estimatePublishCost`
+reports the same in `evm.userPays` / `arweave.userPays`.
+
+#### Users pay for storage (Turbo)
+
+`payment: { storage: 'user' }` sends data items (signed by the user's EVM key, as on the bundler path)
+straight to [Turbo](https://docs.ar.io/build/upload/bundling-services/), which charges that address's
+Turbo credits. Users top up through Turbo with a card or crypto. Items under Turbo's free-tier size
+cost nothing. Before uploading, the publish checks the balance covers the items and fails with
+`InsufficientStorageCreditsError` (with `address`, `requiredWinc`, `balanceWinc`) if not, so nothing
+is half-uploaded.
+
+```typescript
+initPublish({
+  // ...
+  payment: {
+    storage: 'user',
+    // Optional: other Turbo endpoints, or app wallets whose shared credits pay first (x-paid-by)
+    userStorage: { provider: 'turbo', paidBy: ['0xYourAppWallet'] },
+  },
+})
+```
+
+`getTurboBalanceWinc(endpoints, address)` and `getTurboPriceWinc(endpoints, bytes)` help show a
+balance or price before publishing.
+
+#### Approving and billing publishes
+
+`authorizePublish` runs before a publish spends anything (before schema registration, uploads and
+attestations). Use it to confirm the cost with the user, check a quota, or charge them. Return
+`false` or throw to refuse (the publish fails with `PublishNotAuthorizedError`); return `true` or
+nothing to go ahead; return `{ token }` to also send the token to the upload API as the
+`X-Seed-Publish-Authorization` header on that publish's requests, so the operator can meter or
+bill against it.
+
+```typescript
+initPublish({
+  // ...
+  authorizePublish: async ({ item, payment, getEstimate }) => {
+    const estimate = await getEstimate() // fetches prices; skip it if you don't need it
+    const { approved, receiptId } = await myBilling.charge(item.seedLocalId, estimate.totalUsd)
+    return approved ? { token: receiptId } : false
+  },
+})
+```
+
+It can also be passed per publish (`CreatePublishOptions.authorizePublish`). A publish resumed
+after a reload is not asked again once it got past this step; one restored before approval asks
+the config hook. The token is not sent to Turbo.
+
 ### Choosing a chain
 
 Publishing works on any EVM chain with [EAS](https://github.com/ethereum-attestation-service/eas-contracts#deployments) deployed. Pass a viem `chain`; it defaults to Optimism Sepolia. The same chain drives viem reads, transaction routing and the Thirdweb wallet / ConnectButton. When `rpcUrl` is set, Thirdweb uses it too, so Seed's checks and Thirdweb's calls always reach the same node.

package/dist/authorization.d.ts

@@ -0,0 +1,41 @@
+import type { IItem } from '@seedprotocol/sdk';
+import type { ResolvedPublishPayment } from './payment';
+import type { PublishCostEstimate, PublishMode } from './services/publishCost/types';
+/** What an {@link AuthorizePublish} hook is asked to approve. */
+export interface PublishAuthorizationRequest {
+    item: IItem<any>;
+    seedLocalId: string;
+    publishMode: PublishMode;
+    /** Who will pay gas and storage (see `resolvePublishPayment`). */
+    payment: ResolvedPublishPayment;
+    /** Cost estimate for this publish. Fetches market prices, so call it only if you need it. */
+    getEstimate: () => Promise<PublishCostEstimate>;
+}
+/** An approval. `token` goes to the upload API with this publish's requests. */
+export interface PublishAuthorization {
+    /**
+     * Sent as the {@link PUBLISH_AUTHORIZATION_HEADER} header on upload API requests (not to Turbo),
+     * so an operator can meter or bill the publish against it.
+     */
+    token?: string;
+}
+/**
+ * Runs before a publish spends anything (before schema registration, uploads and attestations).
+ * Return `false` or throw to refuse: the publish fails with {@link PublishNotAuthorizedError}.
+ * Return `true`, nothing, or a {@link PublishAuthorization} to go ahead. A resumed publish that
+ * already got past this step is not asked again.
+ */
+export type AuthorizePublish = (request: PublishAuthorizationRequest) => PublishAuthorization | boolean | void | Promise<PublishAuthorization | boolean | void>;
+/** Header carrying {@link PublishAuthorization.token} to the upload API. */
+export declare const PUBLISH_AUTHORIZATION_HEADER = "X-Seed-Publish-Authorization";
+export declare class PublishNotAuthorizedError extends Error {
+    constructor(seedLocalId: string, cause?: unknown);
+}
+/**
+ * Calls the hook and normalizes its answer. Without a hook every publish is approved.
+ * @throws PublishNotAuthorizedError when the hook returns false or throws
+ */
+export declare function runAuthorizePublish(hook: AuthorizePublish | undefined, request: PublishAuthorizationRequest): Promise<PublishAuthorization>;
+/** Headers to add to upload API requests for a publish with this authorization. */
+export declare function publishAuthorizationHeaders(authorization: PublishAuthorization | undefined): Record<string, string>;
+//# sourceMappingURL=authorization.d.ts.map

package/dist/authorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization.d.ts","sourceRoot":"","sources":["../src/authorization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAC9C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAA;AAEpF,iEAAiE;AACjE,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,WAAW,CAAA;IACxB,kEAAkE;IAClE,OAAO,EAAE,sBAAsB,CAAA;IAC/B,6FAA6F;IAC7F,WAAW,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,CAAA;CAChD;AAED,gFAAgF;AAChF,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,2BAA2B,KACjC,oBAAoB,GAAG,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,oBAAoB,GAAG,OAAO,GAAG,IAAI,CAAC,CAAA;AAE3F,4EAA4E;AAC5E,eAAO,MAAM,4BAA4B,iCAAiC,CAAA;AAE1E,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAKjD;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,gBAAgB,GAAG,SAAS,EAClC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,oBAAoB,CAAC,CAa/B;AAED,mFAAmF;AACnF,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,oBAAoB,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEnH"}