@pylo/react 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Okeano GmbH
+ 
+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,113 @@
+# @pylo/react
+
+Type-safe Pylo SDK for React single-page apps. Hooks, a session provider, and a
+typed client, generated from your own Pylo schema.
+
+For Next.js use [`@pylo/nextjs`](../nextjs), which keeps tokens in httpOnly
+cookies. For Expo and React Native use [`@pylo/expo`](../expo).
+
+## Install
+
+```bash
+npm install @pylo/react @tanstack/react-query
+```
+
+## Generate types
+
+Add a `pylo.config.ts` at your project root, then run the generator. It writes
+`.pylo/index.ts` and registers the schema, so no `declare module` is needed.
+
+```bash
+npx pylo generate
+```
+
+## Set up
+
+Your app owns the QueryClient. `PyloProvider` goes inside it, because signing
+out clears the query cache.
+
+```tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { PyloProvider } from "@pylo/react";
+
+const queryClient = new QueryClient();
+
+export function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <PyloProvider appId={import.meta.env.VITE_PYLO_APP_ID}>
+        <Routes />
+      </PyloProvider>
+    </QueryClientProvider>
+  );
+}
+```
+
+## Sign in
+
+```tsx
+import { usePyloAuth } from "@pylo/react";
+
+function SignIn() {
+  const { isLoading, isSignedIn, user, login, logout } = usePyloAuth();
+
+  if (isLoading) return <Spinner />;
+  if (isSignedIn) return <button onClick={() => logout()}>Sign out {user?.email}</button>;
+
+  return <button onClick={() => login(email, password)}>Sign in</button>;
+}
+```
+
+`isLoading` stays true until stored tokens have been read, so an already
+signed-in user never sees a login screen flash.
+
+## Query data
+
+```tsx
+import { createPyloHooks } from "@pylo/react";
+import type { PyloSchema } from "@pylo/types";
+
+const { usePyloList, usePyloUpsert } = createPyloHooks<PyloSchema>();
+
+function Contacts() {
+  const { data, isLoading } = usePyloList("contact", {
+    select: { id: true, name: true, company: { select: { name: true } } },
+  });
+
+  const upsert = usePyloUpsert("contact");
+
+  return <List rows={data} onRename={(id, name) => upsert.mutate({ id, name })} />;
+}
+```
+
+For imperative calls outside a query, `usePyloClient<PyloSchema>()` returns the
+same typed client the server SDK exposes.
+
+## Token storage
+
+Tokens live in `localStorage`, which any script running on your page can read.
+Refresh tokens rotate on every use, but a strong Content Security Policy is what
+actually protects them. If your app has a backend, keep the tokens there and
+proxy requests through it instead.
+
+The token is refreshed before it expires and once more if a request comes back
+unauthorized. Only a rejected refresh token ends the session: a transient server
+error leaves it intact, so a backend deploy does not sign everyone out.
+
+## Bringing your own auth
+
+Pass `getToken` instead, and the provider skips login, logout and refresh
+entirely.
+
+```tsx
+<PyloProvider getToken={() => auth.getAccessToken()}>
+```
+
+## Custom storage
+
+`PyloProvider` takes any `PyloStorage`: three async methods for get, set and
+remove.
+
+```ts
+import type { PyloStorage } from "@pylo/react";
+```

package/dist/chunk-DOPZ5GRU.js

@@ -0,0 +1,540 @@
+import {
+  usePyloTransport
+} from "./chunk-IKQ52QLH.js";
+
+// src/hooks.ts
+import { useCallback, useRef, useState } from "react";
+import {
+  useQuery,
+  useInfiniteQuery,
+  useMutation,
+  useQueryClient
+} from "@tanstack/react-query";
+import {
+  buildListQuery,
+  buildByIdQuery,
+  buildMeQuery,
+  mergeHeaders,
+  flagsToHeaders,
+  capitalize,
+  toAggregateResult
+} from "@pylo/core";
+import {
+  buildUpsertMutation,
+  buildBulkUpsertMutation,
+  buildDeleteMutation,
+  buildIngestEventsMutation,
+  buildEntityAggregateQuery,
+  buildEventAggregateQuery,
+  buildEventListQuery,
+  buildEventPropertyKeysQuery,
+  buildEventFieldValuesQuery
+} from "@pylo/core";
+import {
+  CREATE_UPLOAD_MUTATION,
+  CREATE_DOWNLOAD_MUTATION,
+  buildCreateUploadInput,
+  buildAttachMutation,
+  uploadToUrl,
+  toUploadPart
+} from "@pylo/core";
+function createPyloHooks(options) {
+  var _a;
+  const useTransport = (_a = options == null ? void 0 : options.useTransport) != null ? _a : usePyloTransport;
+  const globalHeaders = options == null ? void 0 : options.headers;
+  function usePyloList(entity, queryOptions) {
+    var _a2, _b, _c;
+    const transport = useTransport();
+    const merged = mergeHeaders(globalHeaders, queryOptions == null ? void 0 : queryOptions.headers);
+    const queryKey = [
+      "pylo",
+      entity,
+      "list",
+      {
+        filter: queryOptions == null ? void 0 : queryOptions.filter,
+        pagination: queryOptions == null ? void 0 : queryOptions.pagination,
+        select: queryOptions == null ? void 0 : queryOptions.select,
+        headers: merged
+      }
+    ];
+    const result = useQuery({
+      queryKey,
+      queryFn: async () => {
+        const { query, variables } = buildListQuery(
+          entity,
+          queryOptions
+        );
+        const data = await transport(query, variables, merged);
+        const listKey = `${entity}List`;
+        return data[listKey];
+      }
+    });
+    return {
+      data: (_b = (_a2 = result.data) == null ? void 0 : _a2.data) != null ? _b : void 0,
+      pagination: (_c = result.data) == null ? void 0 : _c.pagination,
+      isLoading: result.isLoading,
+      error: result.error,
+      refetch: result.refetch
+    };
+  }
+  function usePyloInfiniteList(entity, infiniteOptions) {
+    var _a2;
+    const transport = useTransport();
+    const perPage = (_a2 = infiniteOptions == null ? void 0 : infiniteOptions.perPage) != null ? _a2 : 20;
+    const merged = mergeHeaders(globalHeaders, infiniteOptions == null ? void 0 : infiniteOptions.headers);
+    return useInfiniteQuery({
+      queryKey: [
+        "pylo",
+        entity,
+        "infiniteList",
+        {
+          perPage,
+          filter: infiniteOptions == null ? void 0 : infiniteOptions.filter,
+          select: infiniteOptions == null ? void 0 : infiniteOptions.select,
+          headers: merged
+        }
+      ],
+      queryFn: async ({ pageParam }) => {
+        const runtimeOptions = {
+          select: infiniteOptions == null ? void 0 : infiniteOptions.select,
+          filter: infiniteOptions == null ? void 0 : infiniteOptions.filter,
+          pagination: { page: pageParam, per_page: perPage }
+        };
+        const { query, variables } = buildListQuery(
+          entity,
+          runtimeOptions
+        );
+        const data = await transport(query, variables, merged);
+        const listKey = `${entity}List`;
+        return data[listKey];
+      },
+      initialPageParam: 1,
+      getNextPageParam: (lastPage) => {
+        if (lastPage.pagination.has_more_pages) {
+          return lastPage.pagination.current_page + 1;
+        }
+        return void 0;
+      },
+      select: (queryData) => {
+        const allData = queryData.pages.flatMap(
+          (page) => page.data
+        );
+        return {
+          ...queryData,
+          data: allData,
+          pages: queryData.pages
+        };
+      }
+    });
+  }
+  function usePyloById(entity, id, queryOptions) {
+    const transport = useTransport();
+    const merged = mergeHeaders(globalHeaders, queryOptions == null ? void 0 : queryOptions.headers);
+    return useQuery({
+      queryKey: ["pylo", entity, "byId", id, { select: queryOptions == null ? void 0 : queryOptions.select, headers: merged }],
+      queryFn: async () => {
+        const { query, variables } = buildByIdQuery(
+          entity,
+          id,
+          queryOptions
+        );
+        const data = await transport(query, variables, merged);
+        const byIdKey = `${entity}ById`;
+        const result = data[byIdKey];
+        if (!result) return null;
+        return result.data;
+      },
+      enabled: !!id
+    });
+  }
+  function usePyloMe(queryOptions) {
+    const transport = useTransport();
+    const merged = mergeHeaders(globalHeaders, queryOptions == null ? void 0 : queryOptions.headers);
+    return useQuery({
+      queryKey: ["pylo", "me", { select: queryOptions == null ? void 0 : queryOptions.select, headers: merged }],
+      queryFn: async () => {
+        const { query, variables } = buildMeQuery(
+          queryOptions
+        );
+        const data = await transport(query, variables, merged);
+        return data["me"];
+      }
+    });
+  }
+  function usePyloAggregate(entity, queryOptions) {
+    const transport = useTransport();
+    const merged = mergeHeaders(globalHeaders, queryOptions == null ? void 0 : queryOptions.headers);
+    return useQuery({
+      queryKey: [
+        "pylo",
+        entity,
+        "aggregate",
+        {
+          metrics: queryOptions == null ? void 0 : queryOptions.metrics,
+          groupBy: queryOptions == null ? void 0 : queryOptions.groupBy,
+          filter: queryOptions == null ? void 0 : queryOptions.filter,
+          limit: queryOptions == null ? void 0 : queryOptions.limit,
+          headers: merged
+        }
+      ],
+      queryFn: async () => {
+        const { query, variables } = buildEntityAggregateQuery(
+          capitalize(entity),
+          queryOptions
+        );
+        const data = await transport(query, variables, merged);
+        const result = data["entityInstanceAggregate"];
+        return toAggregateResult(
+          result.rows,
+          result.total,
+          queryOptions
+        );
+      }
+    });
+  }
+  function usePyloEventAggregate(queryOptions) {
+    const transport = useTransport();
+    const merged = mergeHeaders(globalHeaders, queryOptions == null ? void 0 : queryOptions.headers);
+    return useQuery({
+      queryKey: [
+        "pylo",
+        "events",
+        "aggregate",
+        {
+          metrics: queryOptions == null ? void 0 : queryOptions.metrics,
+          groupBy: queryOptions == null ? void 0 : queryOptions.groupBy,
+          filter: queryOptions == null ? void 0 : queryOptions.filter,
+          limit: queryOptions == null ? void 0 : queryOptions.limit,
+          startTime: queryOptions == null ? void 0 : queryOptions.startTime,
+          headers: merged
+        }
+      ],
+      queryFn: async () => {
+        const { query, variables } = buildEventAggregateQuery(
+          queryOptions
+        );
+        const data = await transport(query, variables, merged);
+        const result = data["pyloEventList"];
+        return toAggregateResult(
+          result.data,
+          result.aggregations,
+          queryOptions
+        );
+      }
+    });
+  }
+  function usePyloUpsert(entity, mutationOptions) {
+    const transport = useTransport();
+    const queryClient = useQueryClient();
+    const merged = mergeHeaders(
+      mergeHeaders(globalHeaders, mutationOptions == null ? void 0 : mutationOptions.headers),
+      flagsToHeaders(mutationOptions != null ? mutationOptions : {})
+    );
+    const isDryRun = (mutationOptions == null ? void 0 : mutationOptions.dryRun) === true;
+    return useMutation({
+      ...mutationOptions,
+      mutationFn: async (input) => {
+        const pascalName = capitalize(entity);
+        const { query, variables, field } = buildUpsertMutation(
+          entity,
+          pascalName,
+          input
+        );
+        const data = await transport(query, variables, merged);
+        return data[field].data;
+      },
+      onSuccess: (data, variables, onMutateResult, context) => {
+        var _a2;
+        if (!isDryRun) {
+          void queryClient.invalidateQueries({
+            queryKey: ["pylo", entity]
+          });
+        }
+        (_a2 = mutationOptions == null ? void 0 : mutationOptions.onSuccess) == null ? void 0 : _a2.call(mutationOptions, data, variables, onMutateResult, context);
+      }
+    });
+  }
+  function usePyloBulkUpsert(entity, mutationOptions) {
+    const transport = useTransport();
+    const queryClient = useQueryClient();
+    const merged = mergeHeaders(
+      mergeHeaders(globalHeaders, mutationOptions == null ? void 0 : mutationOptions.headers),
+      flagsToHeaders(mutationOptions != null ? mutationOptions : {})
+    );
+    const isDryRun = (mutationOptions == null ? void 0 : mutationOptions.dryRun) === true;
+    return useMutation({
+      ...mutationOptions,
+      mutationFn: async (inputs) => {
+        const pascalName = capitalize(entity);
+        const { query, variables, field } = buildBulkUpsertMutation(
+          entity,
+          pascalName,
+          inputs
+        );
+        const data = await transport(query, variables, merged);
+        return data[field].data;
+      },
+      onSuccess: (data, variables, onMutateResult, context) => {
+        var _a2;
+        if (!isDryRun) {
+          void queryClient.invalidateQueries({
+            queryKey: ["pylo", entity]
+          });
+        }
+        (_a2 = mutationOptions == null ? void 0 : mutationOptions.onSuccess) == null ? void 0 : _a2.call(mutationOptions, data, variables, onMutateResult, context);
+      }
+    });
+  }
+  function usePyloDelete(entity, mutationOptions) {
+    const transport = useTransport();
+    const queryClient = useQueryClient();
+    const merged = mergeHeaders(
+      mergeHeaders(globalHeaders, mutationOptions == null ? void 0 : mutationOptions.headers),
+      flagsToHeaders(mutationOptions != null ? mutationOptions : {})
+    );
+    const isDryRun = (mutationOptions == null ? void 0 : mutationOptions.dryRun) === true;
+    return useMutation({
+      ...mutationOptions,
+      mutationFn: async (ids) => {
+        const pascalName = capitalize(entity);
+        const { query, variables } = buildDeleteMutation(
+          entity,
+          pascalName,
+          ids
+        );
+        const data = await transport(query, variables, merged);
+        const mutationKey = `delete${pascalName}`;
+        return data[mutationKey].data;
+      },
+      onSuccess: (data, variables, onMutateResult, context) => {
+        var _a2;
+        if (!isDryRun) {
+          void queryClient.invalidateQueries({
+            queryKey: ["pylo", entity]
+          });
+        }
+        (_a2 = mutationOptions == null ? void 0 : mutationOptions.onSuccess) == null ? void 0 : _a2.call(mutationOptions, data, variables, onMutateResult, context);
+      }
+    });
+  }
+  function usePyloIngestEvents(mutationOptions) {
+    const transport = useTransport();
+    const merged = mergeHeaders(
+      mergeHeaders(globalHeaders, mutationOptions == null ? void 0 : mutationOptions.headers),
+      flagsToHeaders(mutationOptions != null ? mutationOptions : {})
+    );
+    return useMutation({
+      ...mutationOptions,
+      mutationFn: async (events) => {
+        const { query, variables } = buildIngestEventsMutation(events);
+        const data = await transport(query, variables, merged);
+        return data["ingestPyloEventData"].data;
+      }
+    });
+  }
+  function usePyloEventList(queryOptions) {
+    const transport = useTransport();
+    const merged = mergeHeaders(globalHeaders, queryOptions == null ? void 0 : queryOptions.headers);
+    return useQuery({
+      queryKey: ["pylo", "events", "list", { ...queryOptions, headers: merged }],
+      queryFn: async () => {
+        const { query, variables } = buildEventListQuery(queryOptions);
+        const data = await transport(query, variables, merged);
+        return data["pyloEventList"];
+      }
+    });
+  }
+  function usePyloEventPropertyKeys(queryOptions) {
+    const transport = useTransport();
+    const merged = mergeHeaders(globalHeaders, queryOptions == null ? void 0 : queryOptions.headers);
+    return useQuery({
+      queryKey: [
+        "pylo",
+        "events",
+        "propertyKeys",
+        { filter: queryOptions == null ? void 0 : queryOptions.filter, headers: merged }
+      ],
+      queryFn: async () => {
+        var _a2;
+        const { query, variables } = buildEventPropertyKeysQuery(queryOptions);
+        const data = await transport(query, variables, merged);
+        return (_a2 = data["pyloEventPropertyKeys"]) != null ? _a2 : [];
+      }
+    });
+  }
+  function usePyloEventFieldValues(field, queryOptions) {
+    const transport = useTransport();
+    const merged = mergeHeaders(globalHeaders, queryOptions == null ? void 0 : queryOptions.headers);
+    return useQuery({
+      queryKey: [
+        "pylo",
+        "events",
+        "fieldValues",
+        field,
+        {
+          startTime: queryOptions == null ? void 0 : queryOptions.startTime,
+          limit: queryOptions == null ? void 0 : queryOptions.limit,
+          headers: merged
+        }
+      ],
+      queryFn: async () => {
+        var _a2;
+        const { query, variables } = buildEventFieldValuesQuery(field, queryOptions);
+        const data = await transport(query, variables, merged);
+        return (_a2 = data["pyloEventFieldValues"]) != null ? _a2 : [];
+      },
+      enabled: !!field
+    });
+  }
+  function usePyloUpload(hookOptions) {
+    const transport = useTransport();
+    const queryClient = useQueryClient();
+    const [isUploading, setIsUploading] = useState(false);
+    const [progress, setProgress] = useState(0);
+    const [error, setError] = useState(null);
+    const [uploadedFiles, setUploadedFiles] = useState([]);
+    const abortRef = useRef(null);
+    const optionsRef = useRef(hookOptions);
+    optionsRef.current = hookOptions;
+    const startUpload = useCallback(
+      async (files, overrides) => {
+        var _a2, _b, _c, _d;
+        const opts = { ...optionsRef.current, ...overrides };
+        const merged = mergeHeaders(globalHeaders, opts.headers);
+        const list = Array.isArray(files) ? files : [files];
+        if (list.length === 0) return [];
+        const controller = new AbortController();
+        abortRef.current = controller;
+        setIsUploading(true);
+        setProgress(0);
+        setError(null);
+        setUploadedFiles([]);
+        let parts = [];
+        let grandTotal;
+        const loadedPerFile = new Array(list.length).fill(0);
+        const doneFlags = new Array(list.length).fill(false);
+        const reportProgress = () => {
+          var _a3, _b2;
+          const loaded = loadedPerFile.reduce((sum, bytes) => sum + bytes, 0);
+          const percent = grandTotal !== void 0 ? grandTotal > 0 ? Math.round(loaded / grandTotal * 100) : 0 : Math.round(
+            doneFlags.filter(Boolean).length / doneFlags.length * 100
+          );
+          setProgress(percent);
+          (_b2 = (_a3 = optionsRef.current) == null ? void 0 : _a3.onProgress) == null ? void 0 : _b2.call(_a3, {
+            loaded,
+            total: grandTotal != null ? grandTotal : loaded,
+            percent
+          });
+        };
+        try {
+          parts = list.map((source) => toUploadPart(source));
+          const sizes = parts.map((part) => part.size);
+          grandTotal = sizes.every((size) => size !== void 0) ? sizes.reduce((sum, size) => sum + (size != null ? size : 0), 0) : void 0;
+          const input = buildCreateUploadInput(opts, list.length);
+          const results = await Promise.all(
+            list.map(async (_source, index) => {
+              var _a3, _b2;
+              const part = parts[index];
+              const data = await transport(
+                CREATE_UPLOAD_MUTATION,
+                { input },
+                merged
+              );
+              const uploadUrl = data.createUpload;
+              await uploadToUrl(uploadUrl.url, part.part, part.fileName, {
+                signal: controller.signal,
+                onProgress: (fileProgress) => {
+                  loadedPerFile[index] = fileProgress.loaded;
+                  reportProgress();
+                }
+              });
+              loadedPerFile[index] = (_a3 = part.size) != null ? _a3 : loadedPerFile[index];
+              doneFlags[index] = true;
+              reportProgress();
+              return {
+                id: uploadUrl.id,
+                fileName: part.fileName,
+                mimeType: part.mimeType,
+                size: (_b2 = part.size) != null ? _b2 : 0
+              };
+            })
+          );
+          if (opts.attachTo) {
+            const { query, variables, entityKey } = buildAttachMutation(
+              opts.entityRelationPath,
+              results.map((result) => result.id),
+              opts.attachTo
+            );
+            await transport(query, variables, merged);
+            void queryClient.invalidateQueries({ queryKey: ["pylo", entityKey] });
+          }
+          void queryClient.invalidateQueries({ queryKey: ["pylo", "pyloMedia"] });
+          setUploadedFiles(results);
+          setProgress(100);
+          (_b = (_a2 = optionsRef.current) == null ? void 0 : _a2.onSuccess) == null ? void 0 : _b.call(_a2, results);
+          return results;
+        } catch (thrown) {
+          controller.abort();
+          const uploadError = thrown instanceof Error ? thrown : new Error(String(thrown));
+          setError(uploadError);
+          (_d = (_c = optionsRef.current) == null ? void 0 : _c.onError) == null ? void 0 : _d.call(_c, uploadError);
+          throw uploadError;
+        } finally {
+          setIsUploading(false);
+          if (abortRef.current === controller) abortRef.current = null;
+        }
+      },
+      [queryClient]
+    );
+    const abort = useCallback(() => {
+      var _a2;
+      (_a2 = abortRef.current) == null ? void 0 : _a2.abort();
+    }, []);
+    const reset = useCallback(() => {
+      setIsUploading(false);
+      setProgress(0);
+      setError(null);
+      setUploadedFiles([]);
+    }, []);
+    return { startUpload, isUploading, progress, error, uploadedFiles, abort, reset };
+  }
+  function usePyloFileUrl(id, queryOptions) {
+    var _a2;
+    const transport = useTransport();
+    const merged = mergeHeaders(globalHeaders, queryOptions == null ? void 0 : queryOptions.headers);
+    return useQuery({
+      queryKey: ["pylo", "files", "downloadUrl", id, { headers: merged }],
+      queryFn: async () => {
+        const data = await transport(
+          CREATE_DOWNLOAD_MUTATION,
+          { id },
+          merged
+        );
+        return data.createDownload.url;
+      },
+      enabled: !!id,
+      staleTime: (_a2 = queryOptions == null ? void 0 : queryOptions.staleTimeMs) != null ? _a2 : 4 * 60 * 1e3
+    });
+  }
+  return {
+    usePyloList,
+    usePyloInfiniteList,
+    usePyloById,
+    usePyloMe,
+    usePyloAggregate,
+    usePyloEventAggregate,
+    usePyloUpsert,
+    usePyloBulkUpsert,
+    usePyloDelete,
+    usePyloIngestEvents,
+    usePyloEventList,
+    usePyloEventPropertyKeys,
+    usePyloEventFieldValues,
+    usePyloUpload,
+    usePyloFileUrl
+  };
+}
+
+export {
+  createPyloHooks
+};