@bates-solutions/squareup 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bates Solutions
+
+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,154 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/React-18+-61DAFB?logo=react&logoColor=white&style=for-the-badge" alt="React" height="28">
+  &nbsp;&nbsp;&nbsp;&nbsp;
+  <img src="https://img.shields.io/badge/Angular-17+-DD0031?logo=angular&logoColor=white&style=for-the-badge" alt="Angular" height="28">
+  &nbsp;&nbsp;&nbsp;&nbsp;
+  <img src="https://img.shields.io/badge/Square-Payments-0066CC?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHJlY3Qgd2lkdGg9IjI0IiBoZWlnaHQ9IjI0IiByeD0iNCIgZmlsbD0iIzAwNjZDQyIvPgo8cGF0aCBkPSJNOC41IDEySDE1LjVWMTMuNUgxMC41VjE1SDE1LjVWMTYuNUgxMC41VjE4SDE1LjVWMTlIMFYxMkg4LjVWMTJIMFYxMkg4LjVWMTJaIiBmaWxsPSJ3aGl0ZSIvPgo8L3N2Zz4K&style=for-the-badge" alt="Square" height="28">
+</p>
+
+<h1 align="center">@bates-solutions/squareup</h1>
+
+<p align="center">
+  <strong>The modern TypeScript SDK for Square payments</strong><br>
+  Build payment experiences in React and Angular with type-safe APIs, fluent builders, and framework-native integrations.
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/version-0.1.0-blue.svg" alt="version 0.1.0">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-5.0+-blue.svg" alt="TypeScript"></a>
+  <br>
+  <img src="https://img.shields.io/badge/tests-329%20passed-brightgreen.svg" alt="Tests">
+  <img src="https://img.shields.io/badge/coverage-99.84%25-brightgreen.svg" alt="Coverage">
+  <img src="https://img.shields.io/badge/React-110%20tests-blue.svg" alt="React Tests">
+  <img src="https://img.shields.io/badge/Angular-133%20tests-red.svg" alt="Angular Tests">
+</p>
+
+---
+
+Stop wrestling with Square's low-level APIs. **squareup** gives you React hooks, Angular services, and a fluent builder API that makes payment integration feel native to your framework. Tokenize cards, process payments, manage orders, and handle webhooks—all with full TypeScript support and zero boilerplate.
+
+## Features
+
+- **Simplified APIs** - Less boilerplate, more productivity
+- **React Integration** - Hooks and components for payments
+- **Angular Integration** - Services with RxJS Observables
+- **Server Utilities** - Webhook verification and middleware
+- **Type-Safe** - Full TypeScript support with strict types
+- **Fluent Builders** - Chainable order and payment construction
+
+## 🧪 Testing & Quality
+
+**329 comprehensive tests** with **99.84% code coverage** ensure reliability and maintainability:
+
+- **React Tests (110)**: Complete coverage of hooks, components, and integrations
+- **Angular Tests (133)**: Full service testing with RxJS observables
+- **Core Tests (86)**: API clients, builders, and utilities
+- **Coverage Breakdown**:
+  - Statements: **99.84%**
+  - Branches: **95.99%**
+  - Functions: **100%**
+  - Lines: **99.84%**
+
+Run tests with:
+
+```bash
+npm test              # All tests
+npm run test:react    # React tests only
+npm run test:angular  # Angular tests only
+npm run test:coverage # With coverage report
+```
+
+## Installation
+
+```bash
+npm install @bates-solutions/squareup square
+```
+
+### Peer Dependencies
+
+```bash
+# For React integration
+npm install react
+
+# For Angular integration
+npm install @angular/core @angular/common rxjs
+```
+
+## 📚 Documentation
+
+- **[Getting Started](./docs/getting-started/)** - Installation and setup guides
+- **[Guides](./docs/guides/)** - Framework-specific tutorials and examples
+- **[API Reference](./docs/api-reference.md)** - Complete API documentation
+- **[Configuration](./docs/getting-started/configuration.md)** - Environment setup
+
+## Quick Start
+
+### Backend
+
+```typescript
+import { createSquareClient } from '@bates-solutions/squareup';
+
+const client = createSquareClient({
+  accessToken: process.env.SQUARE_ACCESS_TOKEN!,
+  environment: 'sandbox',
+});
+
+const payment = await client.payments.create({
+  sourceId: 'cnon:card-nonce',
+  amount: 1000, // $10.00
+  currency: 'USD',
+});
+```
+
+### React
+
+```tsx
+import { SquareProvider, usePayments } from '@bates-solutions/squareup/react';
+
+function App() {
+  return (
+    <SquareProvider applicationId="sq0idp-xxx" locationId="LXXX" environment="sandbox">
+      <PaymentForm />
+    </SquareProvider>
+  );
+}
+
+function PaymentForm() {
+  const { processPayment } = usePayments();
+
+  const handlePayment = async () => {
+    const result = await processPayment({
+      sourceId: 'cnon:card-nonce',
+      amount: 1000, // $10.00
+      currency: 'USD',
+    });
+  };
+
+  return <button onClick={handlePayment}>Pay $10.00</button>;
+}
+```
+
+### Angular
+
+```typescript
+import { SquareModule } from '@bates-solutions/squareup/angular';
+
+@NgModule({
+  imports: [
+    SquareModule.forRoot({
+      accessToken: 'YOUR_ACCESS_TOKEN',
+      environment: 'sandbox',
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.
+
+## License
+
+MIT - see [LICENSE](./LICENSE) for details.

package/README.md.backup

@@ -0,0 +1,292 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/React-18+-61DAFB?logo=react&logoColor=white&style=for-the-badge" alt="React" height="28">
+  &nbsp;&nbsp;&nbsp;&nbsp;
+  <img src="https://img.shields.io/badge/Angular-17+-DD0031?logo=angular&logoColor=white&style=for-the-badge" alt="Angular" height="28">
+  &nbsp;&nbsp;&nbsp;&nbsp;
+  <img src="https://img.shields.io/badge/Square-Payments-0066CC?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHJlY3Qgd2lkdGg9IjI0IiBoZWlnaHQ9IjI0IiByeD0iNCIgZmlsbD0iIzAwNjZDQyIvPgo8cGF0aCBkPSJNOC41IDEySDE1LjVWMTMuNUgxMC41VjE1SDE1LjVWMTYuNUgxMC41VjE4SDE1LjVWMTlIMFYxMkg4LjVWMTJIMFYxMkg4LjVWMTJaIiBmaWxsPSJ3aGl0ZSIvPgo8L3N2Zz4K&style=for-the-badge" alt="Square" height="28">
+</p>
+
+<h1 align="center">@bates-solutions/squareup</h1>
+
+<p align="center">
+  <strong>The modern TypeScript SDK for Square payments</strong><br>
+  Build payment experiences in React and Angular with type-safe APIs, fluent builders, and framework-native integrations.
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/version-0.1.0-blue.svg" alt="version 0.1.0">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-5.0+-blue.svg" alt="TypeScript"></a>
+  <br>
+  <img src="https://img.shields.io/badge/tests-329%20passed-brightgreen.svg" alt="Tests">
+  <img src="https://img.shields.io/badge/coverage-99.84%25-brightgreen.svg" alt="Coverage">
+  <img src="https://img.shields.io/badge/React-110%20tests-blue.svg" alt="React Tests">
+  <img src="https://img.shields.io/badge/Angular-133%20tests-red.svg" alt="Angular Tests">
+</p>
+
+---
+
+Stop wrestling with Square's low-level APIs. **squareup** gives you React hooks, Angular services, and a fluent builder API that makes payment integration feel native to your framework. Tokenize cards, process payments, manage orders, and handle webhooks—all with full TypeScript support and zero boilerplate.
+
+## Features
+
+- **Simplified APIs** - Less boilerplate, more productivity
+- **React Integration** - Hooks and components for payments
+- **Angular Integration** - Services with RxJS Observables
+- **Server Utilities** - Webhook verification and middleware
+- **Type-Safe** - Full TypeScript support with strict types
+- **Fluent Builders** - Chainable order and payment construction
+
+## 🧪 Testing & Quality
+
+**329 comprehensive tests** with **99.84% code coverage** ensure reliability and maintainability:
+
+- **React Tests (110)**: Complete coverage of hooks, components, and integrations
+- **Angular Tests (133)**: Full service testing with RxJS observables
+- **Core Tests (86)**: API clients, builders, and utilities
+- **Coverage Breakdown**:
+  - Statements: **99.84%**
+  - Branches: **95.99%**
+  - Functions: **100%**
+  - Lines: **99.84%**
+
+Run tests with:
+
+```bash
+npm test              # All tests
+npm run test:react    # React tests only
+npm run test:angular  # Angular tests only
+npm run test:coverage # With coverage report
+```
+
+## Installation
+
+```bash
+npm install @bates-solutions/squareup square
+```
+
+### Peer Dependencies
+
+```bash
+# For React integration
+npm install react
+
+# For Angular integration
+npm install @angular/core @angular/common rxjs
+```
+
+## Quick Start
+
+### Core (Node.js/Backend)
+
+```typescript
+import { createSquareClient } from '@bates-solutions/squareup';
+
+const square = createSquareClient({
+  accessToken: process.env.SQUARE_ACCESS_TOKEN!,
+  environment: 'sandbox',
+});
+
+// Create a payment
+const payment = await square.payments.create({
+  sourceId: 'cnon:card-nonce-ok',
+  amount: 1000, // $10.00 in cents
+  currency: 'USD',
+});
+
+// Build an order with fluent API
+const order = await square.orders
+  .builder()
+  .addItem({ name: 'Latte', amount: 450 })
+  .addItem({ catalogId: 'ITEM_123', quantity: 2 })
+  .withTip(100)
+  .build();
+```
+
+### React
+
+```tsx
+import { SquareProvider, useSquarePayment, useOrders } from '@bates-solutions/squareup/react';
+
+function App() {
+  return (
+    <SquareProvider applicationId="sq0idp-xxx" locationId="LXXX" environment="sandbox">
+      <Checkout />
+    </SquareProvider>
+  );
+}
+
+function Checkout() {
+  const { cardRef, tokenize, ready, error } = useSquarePayment();
+  const { create: createOrder } = useOrders();
+
+  const handlePay = async () => {
+    const token = await tokenize();
+    await createOrder({
+      lineItems: [{ name: 'Coffee', amount: 500 }],
+      paymentToken: token,
+    });
+  };
+
+  return (
+    <div>
+      <div ref={cardRef} />
+      <button onClick={handlePay} disabled={!ready}>
+        Pay $5.00
+      </button>
+      {error && <p>{error.message}</p>}
+    </div>
+  );
+}
+```
+
+### Angular
+
+```typescript
+import { SquareModule } from '@bates-solutions/squareup/angular';
+
+@NgModule({
+  imports: [
+    SquareModule.forRoot({
+      applicationId: 'sq0idp-xxx',
+      locationId: 'LXXX',
+      environment: 'sandbox',
+    })
+  ]
+})
+export class AppModule {}
+
+@Component({...})
+export class CheckoutComponent {
+  constructor(private square: SquarePaymentsService) {}
+
+  pay$ = () => this.square.tokenize().pipe(
+    switchMap(token => this.square.createPayment({
+      sourceId: token,
+      amount: 1000
+    }))
+  );
+}
+```
+
+### Server (Webhooks)
+
+```typescript
+import { createNextWebhookHandler } from '@bates-solutions/squareup/server';
+
+// Next.js App Router
+export const POST = createNextWebhookHandler({
+  signatureKey: process.env.SQUARE_WEBHOOK_KEY!,
+  handlers: {
+    'payment.completed': async (event) => {
+      console.log('Payment received:', event.data.id);
+    },
+    'order.fulfillment.updated': async (event) => {
+      await notifyCustomer(event.data.object);
+    },
+  },
+});
+```
+
+## API Reference
+
+### Core Module
+
+| Export                 | Description                            |
+| ---------------------- | -------------------------------------- |
+| `createSquareClient`   | Factory for creating Square API client |
+| `PaymentsService`      | Payment processing operations          |
+| `OrdersService`        | Order management with fluent builder   |
+| `CustomersService`     | Customer CRUD and search               |
+| `CatalogService`       | Product catalog operations             |
+| `InventoryService`     | Stock tracking and adjustments         |
+| `SubscriptionsService` | Recurring billing management           |
+| `InvoicesService`      | Invoice generation and sending         |
+| `LoyaltyService`       | Loyalty program management             |
+
+### React Module (`@bates-solutions/squareup/react`)
+
+| Export             | Description                             |
+| ------------------ | --------------------------------------- |
+| `SquareProvider`   | Context provider for SDK initialization |
+| `useSquare`        | Access Square context                   |
+| `useSquarePayment` | Card tokenization hook                  |
+| `usePayments`      | Payments API hook                       |
+| `useOrders`        | Orders API hook                         |
+| `useCustomers`     | Customers API hook                      |
+| `useCatalog`       | Catalog API hook                        |
+| `CardInput`        | Pre-built card input component          |
+| `PaymentButton`    | Google Pay / Apple Pay button           |
+
+### Angular Module (`@bates-solutions/squareup/angular`)
+
+| Export                   | Description                             |
+| ------------------------ | --------------------------------------- |
+| `SquareModule`           | NgModule with `forRoot()` configuration |
+| `SquareSdkService`       | SDK loading service                     |
+| `SquarePaymentsService`  | Payment operations                      |
+| `SquareOrdersService`    | Order operations                        |
+| `SquareCustomersService` | Customer operations                     |
+| `SquareCatalogService`   | Catalog operations                      |
+| `SquareCardDirective`    | Card input directive                    |
+| `PaymentButtonComponent` | Digital wallet component                |
+
+### Server Module (`@bates-solutions/squareup/server`)
+
+| Export                          | Description                        |
+| ------------------------------- | ---------------------------------- |
+| `verifySignature`               | HMAC-SHA256 signature verification |
+| `createExpressWebhookHandler`   | Express middleware                 |
+| `createNextWebhookHandler`      | Next.js App Router handler         |
+| `createNextPagesWebhookHandler` | Next.js Pages Router handler       |
+| `parseNextWebhook`              | Manual webhook parsing             |
+
+## Money Utilities
+
+```typescript
+import { toCents, fromCents, formatMoney } from '@bates-solutions/squareup';
+
+toCents(10.99); // 1099
+fromCents(1099); // 10.99
+formatMoney(1099, 'USD'); // '$10.99'
+```
+
+## Error Handling
+
+```typescript
+import {
+  SquareApiError,
+  SquareValidationError,
+  SquareNetworkError,
+  SquareAuthenticationError
+} from '@bates-solutions/squareup';
+
+try {
+  await square.payments.create({ ... });
+} catch (error) {
+  if (error instanceof SquareValidationError) {
+    console.log('Invalid input:', error.errors);
+  } else if (error instanceof SquareAuthenticationError) {
+    console.log('Check your access token');
+  } else if (error instanceof SquareNetworkError) {
+    console.log('Network issue, retry later');
+  }
+}
+```
+
+## Configuration
+
+| Option          | Type                        | Required      | Description                            |
+| --------------- | --------------------------- | ------------- | -------------------------------------- |
+| `accessToken`   | `string`                    | Yes           | Square API access token                |
+| `environment`   | `'sandbox' \| 'production'` | No            | API environment (default: `'sandbox'`) |
+| `applicationId` | `string`                    | React/Angular | Web Payments SDK application ID        |
+| `locationId`    | `string`                    | React/Angular | Square location ID                     |
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting a PR.
+
+## License
+
+MIT

package/dist/angular/__tests__/setup.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=setup.d.ts.map

package/dist/angular/__tests__/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../src/angular/__tests__/setup.ts"],"names":[],"mappings":""}

package/dist/angular/__tests__/setup.js

@@ -0,0 +1,5 @@
+"use strict";
+// Angular tests use direct instantiation and mocked NgZone,
+// so Zone.js is not required for our test setup.
+// Keeping Zone.js out avoids hanging processes in CI.
+//# sourceMappingURL=setup.js.map

package/dist/angular/__tests__/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../../src/angular/__tests__/setup.ts"],"names":[],"mappings":";AAAA,4DAA4D;AAC5D,iDAAiD;AACjD,sDAAsD"}

package/dist/angular/components/index.d.ts

@@ -0,0 +1,2 @@
+export { PaymentButtonComponent } from './payment-button.component.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/angular/components/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/angular/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/angular/components/index.js

@@ -0,0 +1,2 @@
+export { PaymentButtonComponent } from './payment-button.component.js';
+//# sourceMappingURL=index.js.map

package/dist/angular/components/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/angular/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/angular/components/payment-button.component.d.ts

@@ -0,0 +1,49 @@
+import { EventEmitter, OnInit, OnDestroy, ChangeDetectorRef } from '@angular/core';
+import { SquareSdkService } from '../services/square-sdk.service.js';
+import type { DigitalWalletOptions } from '../types.js';
+/**
+ * Payment button component for Google Pay / Apple Pay
+ *
+ * @example
+ * ```html
+ * <square-payment-button
+ *   type="googlePay"
+ *   (payment)="onPayment($event)"
+ *   (error)="onError($event)"
+ * ></square-payment-button>
+ *
+ * <square-payment-button
+ *   type="applePay"
+ *   [buttonOptions]="{ buttonColor: 'black' }"
+ *   (payment)="onPayment($event)"
+ * ></square-payment-button>
+ * ```
+ */
+export declare class PaymentButtonComponent implements OnInit, OnDestroy {
+    private sdk;
+    private cdr;
+    /** Payment method type */
+    type: 'googlePay' | 'applePay';
+    /** Button styling options */
+    buttonOptions?: DigitalWalletOptions;
+    /** Emits when button is ready */
+    buttonReady: EventEmitter<void>;
+    /** Emits payment token on success */
+    payment: EventEmitter<string>;
+    /** Emits when an error occurs */
+    error: EventEmitter<Error>;
+    /** Emits when payment is cancelled */
+    cancel: EventEmitter<void>;
+    private containerRef;
+    private paymentMethod;
+    private subscription?;
+    ready: boolean;
+    loading: boolean;
+    constructor(sdk: SquareSdkService, cdr: ChangeDetectorRef);
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    handleClick(): void;
+    private initializePaymentMethod;
+    private tokenize;
+}
+//# sourceMappingURL=payment-button.component.d.ts.map

package/dist/angular/components/payment-button.component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-button.component.d.ts","sourceRoot":"","sources":["../../../src/angular/components/payment-button.component.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,YAAY,EAEZ,MAAM,EACN,SAAS,EAGT,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,KAAK,EAAuB,oBAAoB,EAAe,MAAM,aAAa,CAAC;AAE1F;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAkBa,sBAAuB,YAAW,MAAM,EAAE,SAAS;IA6B5D,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,GAAG;IA7Bb,0BAA0B;IACjB,IAAI,EAAE,WAAW,GAAG,UAAU,CAAe;IAEtD,6BAA6B;IACpB,aAAa,CAAC,EAAE,oBAAoB,CAAC;IAE9C,iCAAiC;IACvB,WAAW,qBAA4B;IAEjD,qCAAqC;IAC3B,OAAO,uBAA8B;IAE/C,iCAAiC;IACvB,KAAK,sBAA6B;IAE5C,sCAAsC;IAC5B,MAAM,qBAA4B;IAG5C,OAAO,CAAC,YAAY,CAA2B;IAE/C,OAAO,CAAC,aAAa,CAAqC;IAC1D,OAAO,CAAC,YAAY,CAAC,CAAe;IAEpC,KAAK,UAAS;IACd,OAAO,UAAS;gBAGN,GAAG,EAAE,gBAAgB,EACrB,GAAG,EAAE,iBAAiB;IAGhC,QAAQ,IAAI,IAAI;IAWhB,WAAW,IAAI,IAAI;IAQnB,WAAW,IAAI,IAAI;YAQL,uBAAuB;YAyBvB,QAAQ;CA4BvB"}