kempo-payments 0.1.1

package/admin/components/ProviderSettings.js

@@ -0,0 +1,310 @@
+import ShadowComponent from '/kempo-ui/components/ShadowComponent.js';
+import '/kempo-ui/components/Icon.js';
+import '/kempo-ui/components/Spinner.js';
+import { html, css } from '/kempo-ui/lit-all.min.js';
+import { getSettings, saveSettings } from '/payments/sdk.js';
+
+/*
+  Connecting the site to a processor.
+
+  Three things on this screen are load-bearing and none of them is the form itself:
+
+  - **The mode banner.** Test keys and live keys look identical at a glance and behave identically
+    until real money is involved. Which one is in use is stated in words, at the top, always.
+  - **The webhook endpoint.** Copy-pasteable, with the exact list of events beside it. A site whose
+    endpoint is wrong takes payments perfectly and never learns that any of them succeeded, and the
+    symptom appears nowhere near the cause.
+  - **Blank means unchanged.** A secret cannot be read back, so its field is always empty. Saving
+    the form after changing the currency must not wipe the keys, and clearing one on purpose is a
+    separate, explicit button.
+*/
+export default class ProviderSettings extends ShadowComponent {
+  static properties = {
+    settings: { type: Object, state: true },
+    providers: { type: Array, state: true },
+    status: { type: Object, state: true },
+    encryptionConfigured: { type: Boolean, state: true },
+    values: { type: Object, state: true },
+    edits: { type: Object, state: true },
+    saving: { type: Boolean, state: true },
+    error: { type: String, state: true },
+    notice: { type: String, state: true },
+  };
+
+  constructor(){
+    super();
+    this.settings = null;
+    this.providers = [];
+    this.status = null;
+    this.encryptionConfigured = true;
+    this.values = {};
+    /*
+      Credential fields are kept apart from the rest. They are the only ones whose current value
+      cannot be read back, so "what is in the box" and "what is stored" are different questions for
+      them and the same question for everything else.
+    */
+    this.edits = {};
+    this.saving = false;
+    this.error = '';
+    this.notice = '';
+  }
+
+  /*
+    Lifecycle
+  */
+
+  connectedCallback(){
+    super.connectedCallback();
+    this.load();
+  }
+
+  /*
+    Data
+  */
+
+  load = async () => {
+    const [error, data] = await getSettings();
+    if(error){
+      this.error = error.msg;
+      return;
+    }
+
+    this.settings = data.settings;
+    this.providers = data.providers;
+    this.status = data.status;
+    this.encryptionConfigured = data.encryptionConfigured;
+    this.values = { ...data.settings };
+    this.edits = {};
+  };
+
+  get provider(){
+    return this.providers.find(entry => entry.name === this.values.provider) || this.providers[0] || null;
+  }
+
+  set = (name, value) => {
+    this.values = { ...this.values, [name]: value };
+  };
+
+  edit = (name, value) => {
+    this.edits = { ...this.edits, [name]: value };
+  };
+
+  save = async () => {
+    this.saving = true;
+    this.error = '';
+    this.notice = '';
+
+    /*
+      Only what was actually typed. An untouched credential field is not sent at all, which is what
+      makes "blank means unchanged" true at the wire rather than only in the route.
+    */
+    const body = {
+      provider: this.values.provider,
+      currency: this.values.currency,
+      capture_method: this.values.captureMethod,
+    };
+
+    for(const field of this.provider?.credentialFields || []){
+      const value = this.edits[field.name];
+      if(value === null || (typeof value === 'string' && value.trim())) body[field.name] = value;
+    }
+
+    const [error] = await saveSettings(body);
+    this.saving = false;
+
+    if(error){
+      this.error = error.msg;
+      return;
+    }
+
+    // Typed keys are dropped the moment they are stored — there is no reason for one to sit in a
+    // form field on an admin's screen for the rest of the afternoon.
+    this.edits = {};
+    this.notice = 'Saved.';
+    await this.load();
+  };
+
+  clear = async name => {
+    this.edits = { ...this.edits, [name]: null };
+    await this.save();
+  };
+
+  copyWebhookUrl = () => {
+    navigator.clipboard?.writeText(this.webhookUrl);
+    this.notice = 'Endpoint URL copied.';
+  };
+
+  get webhookUrl(){
+    return `${window.location.origin}${this.provider?.webhookPath || ''}`;
+  }
+
+  /*
+    Rendering
+  */
+
+  #renderBanner(){
+    if(!this.encryptionConfigured){
+      return html`
+        <div class="card banner tc-danger">
+          <strong>SETTINGS_ENCRYPTION_KEY is not set on this server.</strong>
+          <p class="small">
+            API credentials are encrypted with it, so none can be stored until it exists. Generate one with
+            <code class="ff-mono">node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"</code>,
+            put it in the site’s environment, and restart. Back it up — losing it makes every stored secret unrecoverable.
+          </p>
+        </div>
+      `;
+    }
+
+    if(!this.status?.configured){
+      return html`
+        <div class="card banner tc-warning">
+          <strong>Not connected.</strong>
+          <p class="small">Nothing can be charged until a publishable key and a secret key are saved below.</p>
+        </div>
+      `;
+    }
+
+    if(this.status.mismatchedKeys){
+      return html`
+        <div class="card banner tc-danger">
+          <strong>These keys are from different modes.</strong>
+          <p class="small">
+            The secret key is a ${this.status.mode} key and the publishable key is not. A payment started
+            with one cannot be completed with the other, and the failure shows up in the customer’s browser
+            as a generic error. Use both keys from the same place.
+          </p>
+        </div>
+      `;
+    }
+
+    if(!this.status.hasWebhookSecret){
+      return html`
+        <div class="card banner tc-warning">
+          <strong>No webhook signing secret.</strong>
+          <p class="small">
+            Payments will be taken and none of them will ever be confirmed here — every incoming event is
+            rejected without it. Add the endpoint below, then paste its signing secret in.
+          </p>
+        </div>
+      `;
+    }
+
+    return html`
+      <div class="card banner ${this.status.livemode ? 'tc-danger' : 'tc-success'}">
+        <strong>
+          ${this.status.livemode
+            ? 'Connected in live mode — payments taken here are real.'
+            : 'Connected in test mode. No real money can move.'}
+        </strong>
+      </div>
+    `;
+  }
+
+  #renderCredentials(){
+    const provider = this.provider;
+    if(!provider) return '';
+
+    return provider.credentialFields.map(field => {
+      const isSet = !!this.status?.fields?.[field.name];
+      const value = this.edits[field.name];
+
+      return html`
+        <label class="field">
+          <span class="d-b">${field.label} ${isSet ? html`<span class="small tc-success">· set</span>` : ''}</span>
+          <span class="small tc-muted d-b">${field.help}</span>
+          <input
+            type=${field.type === 'secret' ? 'password' : 'text'}
+            autocomplete="off"
+            placeholder=${isSet ? '•••••••• — leave blank to keep' : field.placeholder}
+            .value=${typeof value === 'string' ? value : ''}
+            @input=${event => this.edit(field.name, event.target.value)}
+          />
+          ${isSet ? html`
+            <button class="link small" ?disabled=${this.saving} @click=${() => this.clear(field.name)}>Clear this key</button>
+          ` : ''}
+        </label>
+      `;
+    });
+  }
+
+  render(){
+    if(!this.settings) return html`<k-spinner></k-spinner>`;
+
+    const provider = this.provider;
+
+    return html`
+      ${this.#renderBanner()}
+      ${this.error ? html`<p class="tc-danger">${this.error}</p>` : ''}
+      ${this.notice ? html`<p class="tc-success small">${this.notice}</p>` : ''}
+
+      <h2>Processor</h2>
+      <label class="field">
+        <span class="small tc-muted d-b">Where payments are taken</span>
+        <select .value=${this.values.provider} @change=${event => this.set('provider', event.target.value)}>
+          ${this.providers.map(entry => html`
+            <option value=${entry.name} ?selected=${entry.name === this.values.provider}>${entry.label}</option>
+          `)}
+        </select>
+      </label>
+
+      ${this.#renderCredentials()}
+
+      <h2>Webhook endpoint</h2>
+      <p class="small tc-muted">
+        Add this in the processor’s dashboard. It is how this site finds out a payment succeeded —
+        the customer’s browser is never trusted for that, because it may be closed, offline, or lying.
+      </p>
+      <div class="endpoint d-f">
+        <input class="ff-mono" type="text" readonly .value=${this.webhookUrl} />
+        <button class="secondary" @click=${this.copyWebhookUrl}><k-icon name="content_copy"></k-icon> Copy</button>
+      </div>
+      ${provider?.webhookEvents?.length ? html`
+        <p class="small tc-muted">Subscribe it to these events:</p>
+        <ul class="events small ff-mono">
+          ${provider.webhookEvents.map(event => html`<li>${event}</li>`)}
+        </ul>
+      ` : ''}
+      <p class="small tc-muted">
+        On a machine the processor cannot reach — localhost — forward them instead:
+        <code class="ff-mono">stripe listen --forward-to ${this.webhookUrl}</code>.
+        That prints its own signing secret, which is the one to paste above while developing.
+      </p>
+
+      <h2>Defaults</h2>
+      <label class="field">
+        <span class="d-b">Currency</span>
+        <span class="small tc-muted d-b">Used when whatever is asking for a payment does not name one</span>
+        <input type="text" maxlength="3" .value=${this.values.currency} @input=${event => this.set('currency', event.target.value)} />
+      </label>
+
+      <label class="field">
+        <span class="d-b">Capture</span>
+        <span class="small tc-muted d-b">
+          Automatic charges the card when the customer confirms. Manual only places a hold, and somebody
+          has to capture it before it expires — right for anything that ships, wrong for anything instant.
+        </span>
+        <select .value=${this.values.captureMethod} @change=${event => this.set('captureMethod', event.target.value)}>
+          <option value="automatic" ?selected=${this.values.captureMethod === 'automatic'}>Automatic</option>
+          <option value="manual" ?selected=${this.values.captureMethod === 'manual'}>Manual</option>
+        </select>
+      </label>
+
+      <button class="primary" ?disabled=${this.saving} @click=${this.save}>
+        ${this.saving ? 'Saving…' : 'Save settings'}
+      </button>
+    `;
+  }
+
+  static styles = css`
+    :host { display: block; }
+    .banner { margin-bottom: var(--spacer); }
+    .banner p { margin-bottom: 0; }
+    .field { margin-bottom: var(--spacer); max-width: 40rem; }
+    .endpoint { align-items: center; margin-bottom: var(--spacer_h); }
+    .endpoint input { margin-bottom: 0; margin-right: var(--spacer_h); flex: 1 1 20rem; }
+    .events { margin-left: var(--spacer); }
+  `;
+}
+
+customElements.define('k-pay-settings', ProviderSettings);

package/admin/components/TestPayment.js

@@ -0,0 +1,283 @@
+import LightComponent from '/kempo-ui/components/LightComponent.js';
+import '/kempo-ui/components/Icon.js';
+import '/kempo-ui/components/Spinner.js';
+import '/payments/components/PaymentForm.js';
+import { html } from '/kempo-ui/lit-all.min.js';
+import { createPayment, getConfig, getPayment } from '/payments/sdk.js';
+import { formatAmount, statusLabel, toMinor } from '/payments/utils/money.js';
+
+/*
+  Takes one real payment, through the real form, against the real processor.
+
+  Worth a tab of its own because nothing else proves the connection works. Saved keys prove nothing
+  — they prove somebody pasted a string. This exercises the whole path end to end: an intent
+  created with the secret key, a form mounted with the publishable key, a confirmation from the
+  browser, and then the part that actually matters — a webhook coming back and moving the payment
+  to Paid. If the last step never happens, the payment sits at "Processing" on this screen, and
+  that is the webhook endpoint telling you it is not configured.
+
+  **Light DOM, and it has to be.** This component hosts `<k-pay-form>`, and Stripe's card fields do
+  not mount inside a shadow root — they reserve the height and then render nothing, with no error
+  anywhere (see PaymentForm.js's own note for what was actually measured). Everything else in this
+  extension's admin is a ShadowComponent; this one cannot be, and neither can anything else that
+  ends up containing the payment form.
+
+  Styling therefore comes from kempo-css utilities rather than a `static styles` block, and the
+  form's width from the 12-column grid.
+*/
+export default class TestPayment extends LightComponent {
+  static properties = {
+    config: { type: Object, state: true },
+    amount: { type: String, state: true },
+    description: { type: String, state: true },
+    captureMethod: { type: String, state: true },
+    payment: { type: Object, state: true },
+    clientSecret: { type: String, state: true },
+    outcome: { type: String, state: true },
+    starting: { type: Boolean, state: true },
+    error: { type: String, state: true },
+  };
+
+  #poll = null;
+
+  constructor(){
+    super();
+    this.config = null;
+    this.amount = '10.00';
+    this.description = 'Test payment';
+    this.captureMethod = '';
+    this.payment = null;
+    this.clientSecret = '';
+    this.outcome = '';
+    this.starting = false;
+    this.error = '';
+  }
+
+  /*
+    Lifecycle
+  */
+
+  connectedCallback(){
+    super.connectedCallback();
+    this.load();
+  }
+
+  disconnectedCallback(){
+    super.disconnectedCallback();
+    clearInterval(this.#poll);
+  }
+
+  load = async () => {
+    const [error, config] = await getConfig();
+    if(error){
+      this.error = error.msg;
+      return;
+    }
+    this.config = config;
+    this.captureMethod = config.captureMethod || 'automatic';
+  };
+
+  /*
+    Actions
+  */
+
+  start = async () => {
+    const amount = toMinor(this.amount, this.config.currency);
+    if(!amount || amount <= 0){
+      this.error = 'Enter an amount to charge';
+      return;
+    }
+
+    this.starting = true;
+    this.error = '';
+    this.outcome = '';
+
+    const [error, result] = await createPayment({
+      amount,
+      currency: this.config.currency,
+      description: this.description || 'Test payment',
+      captureMethod: this.captureMethod,
+      owner: 'kempo-payments',
+      reference: 'admin-test',
+    });
+
+    this.starting = false;
+
+    if(error){
+      this.error = error.msg;
+      return;
+    }
+
+    this.payment = result.payment;
+    this.clientSecret = result.clientSecret;
+  };
+
+  /*
+    The browser saying it worked is not the site knowing it worked — the webhook is. So after the
+    form reports success, this re-reads the payment from the server until the status catches up,
+    which is precisely the round trip being tested. It gives up after thirty seconds and says so,
+    because "it never arrived" is the answer somebody needs, not a spinner forever.
+  */
+  confirmed = () => {
+    this.outcome = 'waiting';
+    const started = Date.now();
+
+    clearInterval(this.#poll);
+    this.#poll = setInterval(async () => {
+      const [error, data] = await getPayment(this.payment.id);
+      if(!error) this.payment = data.payment;
+
+      if(data?.payment?.status === 'succeeded'){
+        clearInterval(this.#poll);
+        this.outcome = 'confirmed';
+        return;
+      }
+
+      if(Date.now() - started > 30000){
+        clearInterval(this.#poll);
+        this.outcome = 'no-webhook';
+      }
+    }, 2000);
+  };
+
+  /*
+    Deliberately no `payment-failed` handler. The form already shows the processor's message inside
+    itself and goes back to accepting a card; repeating it here put the same red line on screen twice
+    and, being set-and-never-cleared, left it there after a successful retry.
+  */
+  reset = () => {
+    clearInterval(this.#poll);
+    this.payment = null;
+    this.clientSecret = '';
+    this.outcome = '';
+    this.error = '';
+  };
+
+  /*
+    Rendering
+  */
+
+  #renderOutcome(){
+    if(this.outcome === 'waiting'){
+      return html`
+        <p class="tc-muted"><k-spinner></k-spinner> Confirmed in the browser. Waiting for the processor’s webhook…</p>
+      `;
+    }
+
+    if(this.outcome === 'confirmed'){
+      return html`
+        <div class="card tc-success">
+          <strong><k-icon name="check_circle"></k-icon> Everything works.</strong>
+          <p class="small">
+            The payment was taken and the webhook came back and confirmed it. That is the whole path —
+            any kempo (CMS) extension listening for <code class="ff-mono">payment:succeeded</code> would have fired just now.
+          </p>
+        </div>
+      `;
+    }
+
+    if(this.outcome === 'no-webhook'){
+      return html`
+        <div class="card tc-warning">
+          <strong>Paid, but nothing came back.</strong>
+          <p class="small">
+            The charge went through — it is ${statusLabel(this.payment.status).toLowerCase()} here, and the
+            processor’s dashboard will show it. What did not happen is the webhook, so this site would never
+            have learnt about it on its own, and no order would ever be fulfilled.
+          </p>
+          <p class="small mb0">
+            Add the endpoint from the Settings tab, or forward events with
+            <code class="ff-mono">stripe listen</code> if this site is running on localhost.
+          </p>
+        </div>
+      `;
+    }
+
+    return '';
+  }
+
+  renderLightDom(){
+    if(this.error && !this.config) return html`<p class="tc-danger">${this.error}</p>`;
+    if(!this.config) return html`<k-spinner></k-spinner>`;
+
+    if(!this.config.configured){
+      return html`
+        <p class="tc-muted">
+          No processor is connected yet. Add its keys on the Settings tab and come back.
+        </p>
+      `;
+    }
+
+    if(this.payment){
+      return html`
+        <div class="row">
+          <div class="span-6 t-span-9 m-span-12">
+            ${this.config.mode === 'live' ? html`
+              <div class="card tc-danger">
+                <strong>These are live keys.</strong>
+                <p class="small mb0">This will charge a real card. Switch to test keys unless that is what you meant.</p>
+              </div>
+            ` : html`
+              <p class="small tc-muted">
+                Test mode. Use card <code class="ff-mono">4242 4242 4242 4242</code>, any future expiry, any CVC.
+                <code class="ff-mono">4000 0025 0000 3155</code> makes the bank ask for authentication;
+                <code class="ff-mono">4000 0000 0000 9995</code> is declined.
+              </p>
+            `}
+
+            <div class="card">
+              <p><strong>${formatAmount(this.payment.amount, this.payment.currency)}</strong> — ${this.payment.description}</p>
+              <k-pay-form
+                client-secret=${this.clientSecret}
+                submit-label="Pay ${formatAmount(this.payment.amount, this.payment.currency)}"
+                @payment-succeeded=${this.confirmed}
+                @payment-processing=${this.confirmed}
+              ></k-pay-form>
+            </div>
+
+            ${this.#renderOutcome()}
+
+            <button class="link" @click=${this.reset}>Start another</button>
+          </div>
+        </div>
+      `;
+    }
+
+    return html`
+      <div class="row">
+        <div class="span-5 t-span-7 m-span-12">
+          <p class="tc-muted">
+            Takes a payment the same way a checkout would, so the keys, the form and the webhook are all
+            exercised at once. In test mode nothing real moves.
+          </p>
+
+          ${this.error ? html`<p class="tc-danger">${this.error}</p>` : ''}
+
+          <label class="mb">
+            <span class="d-b">Amount (${this.config.currency.toUpperCase()})</span>
+            <input type="number" step="any" min="0" .value=${this.amount} @input=${event => { this.amount = event.target.value; }} />
+          </label>
+
+          <label class="mb">
+            <span class="d-b">Description</span>
+            <input type="text" .value=${this.description} @input=${event => { this.description = event.target.value; }} />
+          </label>
+
+          <label class="mb">
+            <span class="d-b">Capture</span>
+            <select .value=${this.captureMethod} @change=${event => { this.captureMethod = event.target.value; }}>
+              <option value="automatic" ?selected=${this.captureMethod === 'automatic'}>Automatic — charge immediately</option>
+              <option value="manual" ?selected=${this.captureMethod === 'manual'}>Manual — authorise only, capture later</option>
+            </select>
+          </label>
+
+          <button class="primary" ?disabled=${this.starting} @click=${this.start}>
+            ${this.starting ? 'Starting…' : 'Start payment'}
+          </button>
+        </div>
+      </div>
+    `;
+  }
+}
+
+customElements.define('k-pay-test', TestPayment);

package/admin/index.page.html

@@ -0,0 +1,81 @@
+<!--
+locked: true
+-->
+<page title="Payments - Admin">
+<content>
+  <script type="module" src="/kempo/components/PermissionTarget.js"></script>
+  <script type="module" src="/kempo-ui/components/Tabs.js"></script>
+  <script type="module" src="/admin/extension/kempo-payments/components/PaymentList.js"></script>
+  <script type="module" src="/admin/extension/kempo-payments/components/ProviderSettings.js"></script>
+  <script type="module" src="/admin/extension/kempo-payments/components/TestPayment.js"></script>
+
+  <div>
+    <h1>Payments</h1>
+    <p class="tc-muted">
+      Every charge this site has taken, and the connection to the processor that takes them. Nothing
+      here holds a card number — those go from the customer's browser straight to the processor, and
+      what is kept is this site's record of what happened to the money.
+    </p>
+
+    <k-tabs id="tabs" active="payments" persistent-id="kempo-payments-admin-tab">
+      <k-tab id="paymentsTab" for="payments">Payments</k-tab>
+      <k-tab id="testTab" for="test">Take a payment</k-tab>
+      <k-tab id="settingsTab" for="settings">Settings</k-tab>
+
+      <k-tab-content id="paymentsContent" name="payments">
+        <k-pay-list></k-pay-list>
+      </k-tab-content>
+
+      <k-tab-content id="testContent" name="test">
+        <k-pay-test></k-pay-test>
+      </k-tab-content>
+
+      <k-tab-content id="settingsContent" name="settings">
+        <k-pay-settings></k-pay-settings>
+      </k-tab-content>
+    </k-tabs>
+
+    <!--
+      Neither of these can wrap the <k-tab>/<k-tab-content> pairs the way k-permission normally
+      wraps content: k-tabs finds its tabs with a direct-child query, so any element between
+      <k-tabs> and <k-tab> — including a hidden one — breaks tab selection outright, not just the
+      display. k-permission-target instead reaches in by id and hides the tab and its pane in place,
+      leaving both exactly where <k-tabs> expects to find them.
+
+      This is a courtesy, same as everywhere else in this file: the actual boundary is server-side,
+      on each route.
+    -->
+    <k-permission-target has="payments:view" target="#paymentsTab, #paymentsContent"></k-permission-target>
+    <k-permission-target has="payments:create" target="#testTab, #testContent"></k-permission-target>
+    <k-permission-target has="payments:settings" target="#settingsTab, #settingsContent"></k-permission-target>
+  </div>
+
+  <script type="module">
+    import { getAllCurrentUserPermissions } from '/kempo/sdk.js';
+
+    await customElements.whenDefined('k-tabs');
+
+    /*
+      The markup defaults to the Payments tab, and persistent-id can restore whichever tab a
+      returning visitor left open — including one this particular visitor cannot see, if their
+      permissions changed since. The k-permission-target elements above hide a tab's own button and
+      pane; this handles never leaving a hidden one selected.
+    */
+    const [error, data] = await getAllCurrentUserPermissions();
+    const permissions = new Set(error ? [] : (data?.permissions || []));
+
+    const tabs = document.getElementById('tabs');
+    if(tabs){
+      const visibility = {
+        payments: permissions.has('payments:view'),
+        test: permissions.has('payments:create'),
+        settings: permissions.has('payments:settings'),
+      };
+      if(!visibility[tabs.active]){
+        const fallback = Object.keys(visibility).find(name => visibility[name]);
+        if(fallback) tabs.active = fallback;
+      }
+    }
+  </script>
+</content>
+</page>

package/admin/nav.global.html

@@ -0,0 +1,3 @@
+<content id="kempo-payments-nav" name="Payments" owner="kempo-payments" enabled="true" locked="true" location="admin-nav-extensions" priority="3">
+<k-aside-item icon="credit_card" href="/admin/extension/kempo-payments/" no-expand>Payments</k-aside-item>
+</content>