@fiscalisto/react 0.0.0-stage → 0.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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Fiscalisto
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,66 @@
1
- # Temporary Holding Version
1
+ # @fiscalisto/react
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Muestre en su aplicación de React la autofactura de Fiscalisto y la liga de datos fiscales de un
4
+ cliente, sin que su comprador salga de su página.
5
+
6
+ ```bash
7
+ npm install @fiscalisto/react
8
+ ```
9
+
10
+ ## Autofactura de un ticket
11
+
12
+ En su servidor registre la venta con el SDK (`fiscalisto.tickets.create`) y mande `ticket.url` a
13
+ su página. Ahí:
14
+
15
+ ```tsx
16
+ import { FiscalistoEmbed } from "@fiscalisto/react";
17
+
18
+ export function Facturar({ url }: { url: string }) {
19
+ return (
20
+ <FiscalistoEmbed
21
+ url={url}
22
+ onComplete={(e) => {
23
+ if (e.kind === "ticket") console.log("Factura timbrada", e.uuid);
24
+ }}
25
+ />
26
+ );
27
+ }
28
+ ```
29
+
30
+ El comprador escribe el total de su ticket y sus datos fiscales, y la factura se timbra en ese
31
+ momento con sus timbres. El marco crece con su contenido.
32
+
33
+ ## En una ventana encima de su página
34
+
35
+ ```tsx
36
+ import { useFiscalistoDialog } from "@fiscalisto/react";
37
+
38
+ export function BotonFacturar({ url }: { url: string }) {
39
+ const { open, dialog } = useFiscalistoDialog({ heading: "Facture su compra" });
40
+ return (
41
+ <>
42
+ <button onClick={() => open(url)}>Facturar mi compra</button>
43
+ {dialog}
44
+ </>
45
+ );
46
+ }
47
+ ```
48
+
49
+ `FiscalistoDialog` hace lo mismo controlado con `open` y `onClose`.
50
+
51
+ ## Datos fiscales de un cliente
52
+
53
+ Con `customer_data_request.url` (POST /v1/customer_data_requests) el mismo componente muestra el
54
+ formulario de datos fiscales: su cliente los escribe o los toma de su constancia, y Fiscalisto
55
+ los revisa con las reglas del SAT. `onComplete` llega con `{ kind: "customer_data" }`.
56
+
57
+ ## Qué llega a su página
58
+
59
+ Solo que terminó (y el UUID de la factura de un ticket). Los datos fiscales de su comprador nunca
60
+ pasan por su página: léalos con la API o espere su webhook (`ticket.invoiced`,
61
+ `customer_data_request.completed`).
62
+
63
+ Sin React, use `<script src="https://fiscalisto.com/js/fiscalisto.js" defer></script>` y
64
+ `Fiscalisto.open(url)` o `Fiscalisto.mount("#factura", url)`.
65
+
66
+ Guía completa: https://fiscalisto.com/docs/api/autofactura
@@ -0,0 +1,54 @@
1
+ import { type CSSProperties, type ReactNode } from "react";
2
+ /**
3
+ * @fiscalisto/react: Fiscalisto's hosted pages inside your React app. A ticket's autofactura
4
+ * portal (`ticket.url` from POST /v1/tickets) or a customer data request
5
+ * (`customer_data_request.url`), in a frame that grows with its content, or on top of your page.
6
+ * The same as fiscalisto.js (https://fiscalisto.com/js/fiscalisto.js), without a script tag.
7
+ *
8
+ * The buyer's fiscal data never reaches your page: when they finish, `onComplete` says so (with
9
+ * the stamped invoice's UUID for a ticket); read the rest with the API or your webhook.
10
+ */
11
+ export type FiscalistoCompletion = {
12
+ kind: "ticket";
13
+ uuid: string | null;
14
+ } | {
15
+ kind: "customer_data";
16
+ };
17
+ export interface FiscalistoEmbedProps {
18
+ /** `ticket.url` or `customer_data_request.url`, as the API answered it. */
19
+ url: string;
20
+ /** The invoice was stamped, or the data was sent. */
21
+ onComplete?: (e: FiscalistoCompletion) => void;
22
+ /** The page finished loading. */
23
+ onReady?: () => void;
24
+ /** Height before the page says its own, in pixels. 560 by default. */
25
+ initialHeight?: number;
26
+ /** The frame's title for screen readers. «Facturación» by default. */
27
+ title?: string;
28
+ className?: string;
29
+ style?: CSSProperties;
30
+ }
31
+ /** The link with ?embed=1; only autofactura and data request links are shown. */
32
+ export declare function embedUrl(url: string): URL;
33
+ /** The page inside yours, as tall as its content. */
34
+ export declare function FiscalistoEmbed({ url, onComplete, onReady, initialHeight, title, className, style, }: FiscalistoEmbedProps): import("react/jsx-runtime").JSX.Element;
35
+ export interface FiscalistoDialogProps extends Omit<FiscalistoEmbedProps, "className" | "style"> {
36
+ open: boolean;
37
+ /** The ×, Esc or a click outside. */
38
+ onClose: () => void;
39
+ /** Shown above the page, like «Facture su compra». */
40
+ heading?: ReactNode;
41
+ }
42
+ /**
43
+ * The page on top of yours. Controlled: `open` and `onClose`. Closes nothing by itself when the
44
+ * buyer finishes, so they can download their PDF and XML; close it from `onComplete` if you want.
45
+ */
46
+ export declare function FiscalistoDialog({ open, onClose, heading, title, ...embed }: FiscalistoDialogProps): import("react/jsx-runtime").JSX.Element | null;
47
+ /** `const { open, dialog } = useFiscalistoDialog()`: `open(url)` from a button, `{dialog}` in your tree. */
48
+ export declare function useFiscalistoDialog(options?: Omit<FiscalistoDialogProps, "open" | "onClose" | "url"> & {
49
+ onClose?: () => void;
50
+ }): {
51
+ open: (url: string) => void;
52
+ close: () => void;
53
+ dialog: import("react/jsx-runtime").JSX.Element | null;
54
+ };
package/dist/index.js ADDED
@@ -0,0 +1,127 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { useCallback, useEffect, useRef, useState, } from "react";
3
+ /** The link with ?embed=1; only autofactura and data request links are shown. */
4
+ export function embedUrl(url) {
5
+ const u = new URL(url);
6
+ if (u.protocol !== "https:" && u.hostname !== "localhost")
7
+ throw new Error("Fiscalisto: la liga debe ser https.");
8
+ if (!/^\/(autofactura|datos)\//.test(u.pathname))
9
+ throw new Error("Fiscalisto: solo se muestran ligas de autofactura o de datos fiscales.");
10
+ u.searchParams.set("embed", "1");
11
+ return u;
12
+ }
13
+ /** The page inside yours, as tall as its content. */
14
+ export function FiscalistoEmbed({ url, onComplete, onReady, initialHeight = 560, title = "Facturación", className, style, }) {
15
+ const ref = useRef(null);
16
+ const [height, setHeight] = useState(initialHeight);
17
+ const src = embedUrl(url);
18
+ const origin = src.origin;
19
+ // The latest callbacks, without listening again on every render.
20
+ const handlers = useRef({ onComplete, onReady });
21
+ handlers.current = { onComplete, onReady };
22
+ useEffect(() => {
23
+ function onMessage(e) {
24
+ if (e.source !== ref.current?.contentWindow || e.origin !== origin)
25
+ return;
26
+ const data = e.data;
27
+ if (!data || data.fiscalisto !== 1)
28
+ return;
29
+ if (data.event === "ready")
30
+ handlers.current.onReady?.();
31
+ else if (data.event === "resize")
32
+ setHeight(Math.max(200, data.height));
33
+ else if (data.event === "completed")
34
+ handlers.current.onComplete?.(data.kind === "ticket"
35
+ ? { kind: "ticket", uuid: data.uuid ?? null }
36
+ : { kind: "customer_data" });
37
+ }
38
+ window.addEventListener("message", onMessage);
39
+ return () => window.removeEventListener("message", onMessage);
40
+ }, [origin]);
41
+ return (_jsx("iframe", { ref: ref, src: src.toString(), title: title, allow: "camera", className: className, style: {
42
+ display: "block",
43
+ width: "100%",
44
+ border: 0,
45
+ background: "transparent",
46
+ height,
47
+ transition: "height .15s ease",
48
+ ...style,
49
+ } }));
50
+ }
51
+ /**
52
+ * The page on top of yours. Controlled: `open` and `onClose`. Closes nothing by itself when the
53
+ * buyer finishes, so they can download their PDF and XML; close it from `onComplete` if you want.
54
+ */
55
+ export function FiscalistoDialog({ open, onClose, heading, title = "Facturación", ...embed }) {
56
+ const close = useRef(null);
57
+ useEffect(() => {
58
+ if (!open)
59
+ return;
60
+ const previous = document.activeElement;
61
+ const overflow = document.documentElement.style.overflow;
62
+ document.documentElement.style.overflow = "hidden";
63
+ close.current?.focus();
64
+ const onKey = (e) => {
65
+ if (e.key === "Escape")
66
+ onClose();
67
+ };
68
+ document.addEventListener("keydown", onKey);
69
+ return () => {
70
+ document.removeEventListener("keydown", onKey);
71
+ document.documentElement.style.overflow = overflow;
72
+ previous?.focus?.();
73
+ };
74
+ }, [open, onClose]);
75
+ if (!open)
76
+ return null;
77
+ return (_jsx("div", { role: "dialog", "aria-modal": "true", "aria-label": title, onClick: (e) => {
78
+ if (e.target === e.currentTarget)
79
+ onClose();
80
+ }, style: {
81
+ position: "fixed",
82
+ inset: 0,
83
+ zIndex: 2147483000,
84
+ display: "flex",
85
+ alignItems: "flex-start",
86
+ justifyContent: "center",
87
+ overflowY: "auto",
88
+ padding: "24px 12px",
89
+ background: "rgba(17,17,17,.45)",
90
+ }, children: _jsxs("div", { style: {
91
+ position: "relative",
92
+ width: "100%",
93
+ maxWidth: 480,
94
+ margin: "auto 0",
95
+ borderRadius: 16,
96
+ overflow: "hidden",
97
+ background: "#fff",
98
+ boxShadow: "0 24px 60px rgba(0,0,0,.25)",
99
+ }, children: [_jsx("button", { ref: close, type: "button", "aria-label": "Cerrar", onClick: onClose, style: {
100
+ position: "absolute",
101
+ top: 8,
102
+ right: 8,
103
+ zIndex: 1,
104
+ width: 32,
105
+ height: 32,
106
+ border: 0,
107
+ borderRadius: 999,
108
+ background: "rgba(0,0,0,.06)",
109
+ color: "#333",
110
+ font: "20px/32px system-ui, sans-serif",
111
+ cursor: "pointer",
112
+ }, children: "\u00D7" }), heading && (_jsx("div", { style: {
113
+ padding: "16px 48px 0 20px",
114
+ font: "600 16px system-ui, sans-serif",
115
+ }, children: heading })), _jsx(FiscalistoEmbed, { title: title, ...embed })] }) }));
116
+ }
117
+ /** `const { open, dialog } = useFiscalistoDialog()`: `open(url)` from a button, `{dialog}` in your tree. */
118
+ export function useFiscalistoDialog(options = {}) {
119
+ const [url, setUrl] = useState(null);
120
+ const { onClose, ...rest } = options;
121
+ const close = useCallback(() => {
122
+ setUrl(null);
123
+ onClose?.();
124
+ }, [onClose]);
125
+ const dialog = url ? (_jsx(FiscalistoDialog, { ...rest, url: url, open: true, onClose: close })) : null;
126
+ return { open: setUrl, close, dialog };
127
+ }
package/package.json CHANGED
@@ -1,6 +1,38 @@
1
1
  {
2
- "name": "@fiscalisto/react",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
2
+ "name": "@fiscalisto/react",
3
+ "version": "0.1.0",
4
+ "description": "Componentes de React para mostrar en su página la autofactura de Fiscalisto y la liga de datos fiscales de un cliente.",
5
+ "keywords": [
6
+ "cfdi",
7
+ "factura",
8
+ "autofactura",
9
+ "react",
10
+ "sat",
11
+ "mexico",
12
+ "fiscalisto"
13
+ ],
14
+ "homepage": "https://fiscalisto.com/docs/api/autofactura",
15
+ "license": "MIT",
16
+ "type": "module",
17
+ "sideEffects": false,
18
+ "main": "./dist/index.js",
19
+ "types": "./dist/index.d.ts",
20
+ "exports": {
21
+ ".": {
22
+ "types": "./dist/index.d.ts",
23
+ "default": "./dist/index.js"
24
+ }
25
+ },
26
+ "files": [
27
+ "dist",
28
+ "README.md",
29
+ "LICENSE"
30
+ ],
31
+ "peerDependencies": {
32
+ "react": ">=18"
33
+ },
34
+ "scripts": {
35
+ "build": "rm -rf dist && tsc -p tsconfig.json",
36
+ "prepublishOnly": "npm run build"
37
+ }
38
+ }