How to Integrate Lovable with Wave

Go to developer.waveapps.com and log in with your Wave account credentials. Click 'Create an Application'. Fill in your application name, description, and website URL. Set the Redirect URL to your Lovable app's OAuth callback path (e.g., https://your-app.lovable.app/auth/wave/callback). After creating the application, you'll see your Client ID and Client Secret on the application detail page. Copy both — the Client Secret is shown only on creation and cannot be retrieved again (only regenerated). Wave's OAuth2 scopes are straightforward. The main scope is 'account:* business:*' which grants access to all business data the user owns. For read-only integrations, use 'account:read business:read'. For creating invoices and managing customers, you need 'business:write' included. Wave's authorization URL is https://authorization.waveapps.com/oauth2/authorize. The token endpoint is https://api.waveapps.com/oauth2/token. The GraphQL API endpoint (used for all data operations) is https://gql.waveapps.com/graphql/public.

Open your Lovable project, click '+', select 'Cloud', and expand Secrets. Add WAVE_CLIENT_ID, WAVE_CLIENT_SECRET, and WAVE_REDIRECT_URI as encrypted environment variables. For the OAuth2 authorization flow, build a 'Connect Wave' button that redirects users to Wave's authorization URL with the required parameters: client_id, redirect_uri, response_type=code, and scope. Include a state parameter (random UUID stored in Supabase against the user_id) to prevent CSRF attacks. At the callback URL, extract the authorization code from the query parameters, verify the state parameter matches the stored value, then call a Wave OAuth Edge Function that exchanges the code for tokens. POST to https://api.waveapps.com/oauth2/token with grant_type=authorization_code, code, client_id, client_secret, and redirect_uri. Store the returned access_token and refresh_token in a wave_tokens Supabase table. Wave access tokens expire after 24 hours and refresh tokens expire after 30 days. Implement token refresh using grant_type=refresh_token before making API calls when the token is within 1 hour of expiry.

1// supabase/functions/wave-oauth/index.ts
2import { serve } from "https://deno.land/std@0.168.0/http/server.ts";
3import { createClient } from "https://esm.sh/@supabase/supabase-js@2";
4
5const CLIENT_ID = Deno.env.get("WAVE_CLIENT_ID") ?? "";
6const CLIENT_SECRET = Deno.env.get("WAVE_CLIENT_SECRET") ?? "";
7const REDIRECT_URI = Deno.env.get("WAVE_REDIRECT_URI") ?? "";
8const TOKEN_URL = "https://api.waveapps.com/oauth2/token";
9const GQL_URL = "https://gql.waveapps.com/graphql/public";
10const corsHeaders = { "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Methods": "POST, OPTIONS", "Access-Control-Allow-Headers": "Content-Type, Authorization" };
11
12serve(async (req) => {
13  if (req.method === "OPTIONS") return new Response(null, { headers: corsHeaders });
14  const supabase = createClient(Deno.env.get("SUPABASE_URL") ?? "", Deno.env.get("SUPABASE_SERVICE_ROLE_KEY") ?? "");
15  const body = await req.json();
16
17  try {
18    if (body.action === "exchange") {
19      const { code, user_id } = body;
20      const res = await fetch(TOKEN_URL, {
21        method: "POST",
22        headers: { "Content-Type": "application/x-www-form-urlencoded" },
23        body: new URLSearchParams({ grant_type: "authorization_code", code, client_id: CLIENT_ID, client_secret: CLIENT_SECRET, redirect_uri: REDIRECT_URI }),
24      });
25      const data = await res.json();
26      if (!data.access_token) throw new Error(data.error_description ?? "Token exchange failed");
27
28      // Fetch businesses
29      const gqlRes = await fetch(GQL_URL, {
30        method: "POST",
31        headers: { "Authorization": `Bearer ${data.access_token}`, "Content-Type": "application/json" },
32        body: JSON.stringify({ query: `query { businesses(page: 1, pageSize: 10) { edges { node { id name } } } }` }),
33      });
34      const gqlData = await gqlRes.json();
35      const businessId = gqlData.data?.businesses?.edges?.[0]?.node?.id ?? "";
36
37      const expiresAt = new Date(Date.now() + data.expires_in * 1000).toISOString();
38      await supabase.from("wave_tokens").upsert({ user_id, access_token: data.access_token, refresh_token: data.refresh_token, expires_at: expiresAt, business_id: businessId }, { onConflict: "user_id" });
39      return new Response(JSON.stringify({ success: true, business_id: businessId }), { headers: { ...corsHeaders, "Content-Type": "application/json" } });
40    }
41
42    if (body.action === "get-token") {
43      const { user_id } = body;
44      const { data: token } = await supabase.from("wave_tokens").select("*").eq("user_id", user_id).single();
45      if (!token) throw new Error("No Wave connection found.");
46
47      if (new Date(token.expires_at) < new Date(Date.now() + 3_600_000)) {
48        const res = await fetch(TOKEN_URL, {
49          method: "POST",
50          headers: { "Content-Type": "application/x-www-form-urlencoded" },
51          body: new URLSearchParams({ grant_type: "refresh_token", refresh_token: token.refresh_token, client_id: CLIENT_ID, client_secret: CLIENT_SECRET }),
52        });
53        const data = await res.json();
54        const expiresAt = new Date(Date.now() + data.expires_in * 1000).toISOString();
55        await supabase.from("wave_tokens").update({ access_token: data.access_token, refresh_token: data.refresh_token, expires_at: expiresAt }).eq("user_id", user_id);
56        return new Response(JSON.stringify({ access_token: data.access_token, business_id: token.business_id }), { headers: { ...corsHeaders, "Content-Type": "application/json" } });
57      }
58      return new Response(JSON.stringify({ access_token: token.access_token, business_id: token.business_id }), { headers: { ...corsHeaders, "Content-Type": "application/json" } });
59    }
60
61    return new Response(JSON.stringify({ error: "Unknown action" }), { status: 400, headers: corsHeaders });
62  } catch (err) {
63    return new Response(JSON.stringify({ error: err.message }), { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } });
64  }
65});

All Wave data operations use GraphQL through a single endpoint. Unlike REST APIs where each resource type has its own URL, you send all queries and mutations to https://gql.waveapps.com/graphql/public with the query or mutation in the request body. Create a central Wave data Edge Function that accepts a query/mutation string and variables object, obtains the user's access token via wave-oauth, and POSTs the GraphQL request to Wave. This pattern works for any Wave operation rather than hardcoding specific operations in separate functions. Key Wave GraphQL operations: Query businesses to list all businesses and get the businessId needed for other operations. Query invoices(businessId, page, pageSize) to list invoices with their status, amounts, and customer info. Mutation invoiceCreate(input: {businessId, customerId, ...}) to create new invoices. Query customers(businessId) to list customers. Mutation customerCreate(input: {businessId, name, email, ...}) to add new customers. Because Wave's responses nest deeply — invoices are inside businesses, which are inside the user — structure your GraphQL queries to fetch exactly what you need. Avoid fetching entire business trees when you only need invoice summaries. Use pagination (page and pageSize arguments) to avoid timeouts on accounts with large transaction histories.

With the GraphQL Edge Function working, build the Wave accounting dashboard. The key difference from REST-based dashboards is that you compose your GraphQL queries to fetch exactly the data shape your UI needs rather than making multiple sequential API calls. For an invoicing overview, write a single GraphQL query that fetches the business name, total outstanding receivables, recent invoices with customer names and amounts, and invoice status counts all in one request. This is one of GraphQL's main advantages — your Edge Function makes one network call instead of four. For customer management, build a customer list that fetches customers with their invoice counts and total billed amounts. The Wave GraphQL schema allows querying customer invoices as a nested field within the customer query — ask Lovable to write the query that fetches customers with their associated invoice summaries. For creating invoices, build a form that lets users select a customer (from the Wave customers query), add line items with description, quantity, and unit price, set a due date, and click 'Create Invoice'. The form sends a invoiceCreate GraphQL mutation with the appropriate variables. After creation, Wave returns the invoiceId and invoice number.