@fayz-ai/plugin-fiscal-br 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Faya Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# @fayz-ai/plugin-fiscal-br
+
+**Status:** preview. Sandbox and SEFAZ homologation only; production emission is
+intentionally not exposed by this package.
+
+`plugin-fiscal-br` is the Brazilian fiscal addon hosted by
+`@fayz-ai/plugin-financial`. Its first provider is TecnoSpeed PlugNotas and its
+first document journey is NFC-e (model 65) for a completed restaurant order.
+
+```bash
+npm install @fayz-ai/plugin-fiscal-br
+```
+
+## Ownership boundary
+
+- `plugin-financial` owns `plg_financial_nfe`, the fiscal document shown to the
+  operator. There is no second PlugNotas invoice table.
+- `plugin-fiscal-br` owns the provider connection contract, durable command,
+  retry/recovery trail, webhook receipt and emitter claim.
+- The app owns the Edge Function implementation and the setup panel, because it
+  owns deployment, origins and product-specific composition.
+- `packages/db` owns `connections`, `orders` and `items`. The addon consumes
+  those canonical contracts; it does not recreate `plg_connections` or
+  `order_items` from the pre-squash implementation.
+
+## Why the command is durable
+
+Sending an NFC-e and losing the HTTP response is ambiguous: the provider may
+have accepted the document even though the caller timed out. Repeating the POST
+without first consulting the provider can create a duplicate fiscal effect.
+
+The migration therefore creates `plg_fiscalbr_nfce_jobs` before any provider
+call. The job keeps a frozen order snapshot and a stable idempotency key. A
+timeout moves it to `waiting`; a recovery worker claims it with `SKIP LOCKED`,
+queries PlugNotas and only retries with the same integration id when the
+provider confirms the first request does not exist. Webhooks and recovery update
+the same job and the same `plg_financial_nfe` row.
+
+## Credential and certificate boundary
+
+The browser stores no PlugNotas API key, A1 bytes, A1 password, CSC code or CSC
+token. The setup form uploads the A1 and its password to the app-owned server
+boundary over the authenticated request; the boundary forwards them to the
+provider and discards them. `connections.settings` receives only readiness and
+non-secret metadata such as expiry and an optional fingerprint.
+
+CSC belongs to the emitter. It must be collected during that tenant's setup and
+sent to the server boundary. It is not a pool-wide `PLUGNOTAS_CSC_CONFIG_JSON`
+secret and cannot be shared between tenants. This package deliberately removed
+that old draft contract.
+
+The PlugNotas software-house API key remains a server-only deployment secret.
+No secret value is committed here; the manifest contains names only so deploy
+and diagnostics can report missing configuration.
+
+## Runtime contract
+
+```tsx
+import { createFinancialPlugin } from '@fayz-ai/plugin-financial'
+import {
+  createPlugNotasFinancialProvider,
+  createPlugNotasPlugin,
+} from '@fayz-ai/plugin-fiscal-br'
+
+const fiscalProvider = createPlugNotasFinancialProvider({
+  base: financialProvider,
+  gateway: appOwnedPlugNotasGateway,
+})
+
+const plugins = [
+  createFinancialPlugin({
+    dataProvider: fiscalProvider,
+    fiscalProvider: {
+      label: 'PlugNotas',
+      models: ['nfce'],
+      requiresOrder: true,
+    },
+  }),
+  createPlugNotasPlugin({ SetupPanel: AppOwnedSetupPanel }),
+]
+```
+
+The decorator never trusts a transient provider response as the ledger. Issue,
+refresh and cancel always return the document read back from the database after
+the server operation. XML, DANFCE and cancellation XML use short-lived URLs
+resolved on demand instead of durable signed URLs stored on the fiscal row.
+
+## What this draft does not authorize
+
+- It does not apply the migration to a Supabase project.
+- It does not deploy the Edge Function.
+- It does not create or rotate any secret.
+- It does not enable production emission.
+- It does not claim homologation passed; that needs a real emitter, A1, CSC and
+  an observed issue/status/artifact/cancel journey.
+
+The companion NeoChef PR supplies the application Edge Function and composition.
+The full ownership map and rollout gates are documented in
+[`docs/integrations/PLUGNOTAS-NFCE.md`](../../docs/integrations/PLUGNOTAS-NFCE.md).

package/dist/connectors/plugnotas.d.ts

@@ -0,0 +1,34 @@
+import type React from 'react';
+import { type ConnectorDefinition } from '@fayz-ai/core';
+import type { PlugNotasConnectorClient, PlugNotasSetupState } from '../types';
+export declare const PLUGNOTAS_CONNECTOR_ID = "plugnotas";
+export declare const PLUGNOTAS_FIELDS: readonly [{
+    readonly key: "emitterCnpj";
+    readonly label: "CNPJ do emitente";
+    readonly type: "text";
+    readonly placeholder: "00.000.000/0000-00";
+}];
+export declare const PLUGNOTAS_SETTINGS: readonly [{
+    readonly key: "environment";
+    readonly label: "Ambiente fiscal";
+    readonly description: "Sandbox simula o emissor. Homologação envia para a SEFAZ sem valor fiscal.";
+    readonly type: "select";
+    readonly options: [{
+        readonly value: "sandbox";
+        readonly label: "Sandbox simulado";
+    }, {
+        readonly value: "homologation";
+        readonly label: "Homologação SEFAZ";
+    }];
+    readonly requiredToOperate: true;
+    readonly defaultValue: "sandbox";
+}];
+export declare function isValidCnpj(value: string): boolean;
+export interface CreatePlugNotasConnectorOptions {
+    client?: PlugNotasConnectorClient;
+    SetupPanel?: React.ComponentType;
+}
+export declare function createPlugNotasConnector(options?: CreatePlugNotasConnectorOptions): ConnectorDefinition;
+/** Persist only server-confirmed readiness and non-secret certificate metadata. */
+export declare function markPlugNotasEmitterReady(input: PlugNotasSetupState): Promise<void>;
+//# sourceMappingURL=plugnotas.d.ts.map

package/dist/connectors/plugnotas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugnotas.d.ts","sourceRoot":"","sources":["../../src/connectors/plugnotas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAML,KAAK,mBAAmB,EAGzB,MAAM,eAAe,CAAA;AACtB,OAAO,KAAK,EAAE,wBAAwB,EAAwB,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAEnG,eAAO,MAAM,sBAAsB,cAAc,CAAA;AAIjD,eAAO,MAAM,gBAAgB;;;;;EAOiB,CAAA;AAE9C,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;EAWkB,CAAA;AA0BjD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAWlD;AAqDD,MAAM,WAAW,+BAA+B;IAC9C,MAAM,CAAC,EAAE,wBAAwB,CAAA;IACjC,UAAU,CAAC,EAAE,KAAK,CAAC,aAAa,CAAA;CACjC;AAED,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,+BAAoC,GAAG,mBAAmB,CA0E3G;AAED,mFAAmF;AACnF,wBAAsB,yBAAyB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBzF"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import { type PluginManifest } from '@fayz-ai/core';
+import { type CreatePlugNotasConnectorOptions } from './connectors/plugnotas';
+export * from './connectors/plugnotas';
+export * from './lib/financial-provider';
+export * from './types';
+export interface CreatePlugNotasPluginOptions extends CreatePlugNotasConnectorOptions {
+}
+/**
+ * Fiscal Brasil is an addon: Financial owns the fiscal document, while this
+ * package owns the provider connection and its asynchronous delivery trail.
+ */
+export declare function createPlugNotasPlugin(options?: CreatePlugNotasPluginOptions): PluginManifest;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAA;AACjE,OAAO,EAA4B,KAAK,+BAA+B,EAAE,MAAM,wBAAwB,CAAA;AAGvG,cAAc,wBAAwB,CAAA;AACtC,cAAc,0BAA0B,CAAA;AACxC,cAAc,SAAS,CAAA;AAEvB,MAAM,WAAW,4BAA6B,SAAQ,+BAA+B;CAAG;AAExF;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,4BAAiC,GAAG,cAAc,CAiFhG"}