@agnocon/piece-bokio 0.0.8

package/src/lib/actions/create-invoice.ts

@@ -0,0 +1,145 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { bokioAuth } from '../common/auth';
+import { makeRequest } from '../common/client';
+import { HttpMethod } from '@agnocon/pieces-common';
+import { lineItemsProps } from '../common/props';
+
+export const createInvoice = createAction({
+  auth: bokioAuth,
+  name: 'createInvoice',
+  displayName: 'Create Invoice',
+  description: 'Creates a new draft invoice in Bokio',
+  audience: 'both',
+  aiMetadata: { description: 'Creates a new draft invoice in a Bokio company with a single line item. Use to start a new customer invoice; invoice date, due date, and item type are required, and the customer is linked by passing the customer UUID. Not idempotent — each call creates a separate draft invoice.', idempotent: false },
+  props: {
+    invoiceType: Property.StaticDropdown({
+      displayName: 'Invoice Type',
+      description: 'Type of invoice',
+      required: false,
+      options: {
+        options: [
+          { label: 'Invoice', value: 'invoice' },
+          { label: 'Cash Invoice', value: 'cashInvoice' },
+        ],
+      },
+    }),
+    customerRef: Property.ShortText({
+      displayName: 'Customer ID',
+      description: 'UUID of the customer',
+      required: false,
+    }),
+    invoiceDate: Property.ShortText({
+      displayName: 'Invoice Date',
+      description: 'Invoice date (YYYY-MM-DD)',
+      required: true,
+    }),
+    dueDate: Property.ShortText({
+      displayName: 'Due Date',
+      description: 'Due date (YYYY-MM-DD)',
+      required: true,
+    }),
+    orderNumberReference: Property.ShortText({
+      displayName: 'Order Number Reference',
+      description: 'The order number associated with the invoice',
+      required: false,
+    }),
+    currency: Property.ShortText({
+      displayName: 'Currency',
+      description: 'ISO 4217 currency code (e.g., SEK, EUR, USD)',
+      required: false,
+    }),
+    currencyRate: Property.Number({
+      displayName: 'Currency Rate',
+      description: 'Currency rate (defaults to 1)',
+      required: false,
+    }),
+    itemType: Property.StaticDropdown({
+      displayName: 'Item Type',
+      description: 'Type of the line item',
+      required: true,
+      options: {
+        options: [
+          { label: 'Sales Item', value: 'salesItem' },
+          { label: 'Description Only Item', value: 'descriptionOnlyItem' },
+        ],
+      },
+    }),
+    dynamicProps: lineItemsProps,
+  },
+  async run(context) {
+    const {
+      invoiceType,
+      customerRef,
+      invoiceDate,
+      dueDate,
+      orderNumberReference,
+      currency,
+      currencyRate,
+      itemType,
+      dynamicProps,
+    } = context.propsValue;
+    const { api_key, companyId } = context.auth.props;
+
+    const body: any = {
+      type: invoiceType || 'invoice',
+      invoiceDate,
+      dueDate,
+    };
+
+    if (customerRef) {
+      body.customerRef = {
+        id: customerRef,
+      };
+    }
+
+    if (orderNumberReference) {
+      body.orderNumberReference = orderNumberReference;
+    }
+
+    if (currency) {
+      body.currency = currency;
+    }
+
+    if (currencyRate !== undefined && currencyRate !== null) {
+      body.currencyRate = currencyRate;
+    }
+    const lineItems: any = {};
+    if (itemType === 'salesItem' && dynamicProps) {
+      lineItems.itemType = itemType;
+      body.description = dynamicProps?.['description'];
+      lineItems.quantity = dynamicProps['quantity'];
+      lineItems.unitPrice = dynamicProps['unitPrice'];
+
+      if (dynamicProps['itemRefId']) {
+        lineItems.itemRef = {
+          id: dynamicProps['itemRefId'],
+        };
+      }
+
+      if (dynamicProps['productType']) {
+        lineItems.productType = dynamicProps['productType'];
+      }
+
+      if (dynamicProps['unitType']) {
+        lineItems.unitType = dynamicProps['unitType'];
+      }
+
+      if (
+        dynamicProps['taxRate'] !== undefined &&
+        dynamicProps['taxRate'] !== null
+      ) {
+        lineItems.taxRate = dynamicProps['taxRate'];
+      }
+    }
+    body.lineItems = [lineItems];
+    
+    const response = await makeRequest(
+      api_key,
+      HttpMethod.POST,
+      `/companies/${companyId}/invoices`,
+      body
+    );
+
+    return response;
+  },
+});

package/src/lib/actions/find-customer.ts

@@ -0,0 +1,75 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { bokioAuth } from '../common/auth';
+import { makeRequest } from '../common/client';
+import { HttpMethod } from '@agnocon/pieces-common';
+
+export const findCustomer = createAction({
+  auth: bokioAuth,
+  name: 'findCustomer',
+  displayName: 'Find Customer',
+  description: 'Find customers in Bokio by filtering and pagination',
+  audience: 'both',
+  aiMetadata: { description: 'Lists customers in a Bokio company with pagination, optionally filtered by name, type, VAT number, or organization number. Leaving the filter empty returns all customers; supplying a filter type and value narrows to matching records. Use to look up a customer or their ID. Idempotent read-only lookup.', idempotent: true },
+  props: {
+    filterType: Property.StaticDropdown({
+      displayName: 'Filter Type',
+      description: 'Type of filter to use',
+      required: false,
+      options: {
+        options: [
+          { label: 'Name', value: 'name' },
+          { label: 'Type', value: 'type' },
+          { label: 'VAT Number', value: 'vatNumber' },
+          { label: 'Organization Number', value: 'orgNumber' },
+        ],
+      },
+    }),
+    filterValue: Property.ShortText({
+      displayName: 'Filter Value',
+      description: 'Value to filter by',
+      required: false,
+    }),
+    page: Property.Number({
+      displayName: 'Page',
+      description: 'Page number (defaults to 1)',
+      required: false,
+    }),
+    pageSize: Property.Number({
+      displayName: 'Page Size',
+      description: 'Number of items per page (max 100, defaults to 25)',
+      required: false,
+    }),
+  },
+  async run(context) {
+    const { filterType, filterValue, page, pageSize } = context.propsValue;
+    const { api_key, companyId } = context.auth.props;
+
+    let query = '';
+    if (filterType && filterValue) {
+      query = `${filterType}=='${filterValue}'`;
+    }
+
+    const params = new URLSearchParams();
+    if (page !== undefined && page !== null) {
+      params.append('page', String(page));
+    } else {
+      params.append('page', '1');
+    }
+
+    if (pageSize !== undefined && pageSize !== null) {
+      params.append('pageSize', String(pageSize));
+    } else {
+      params.append('pageSize', '25');
+    }
+
+    if (query) {
+      params.append('query', query);
+    }
+
+    const url = `/companies/${companyId}/customers?${params.toString()}`;
+
+    const response = await makeRequest(api_key, HttpMethod.GET, url);
+
+    return response;
+  },
+});

package/src/lib/actions/get-a-journal-entry.ts

@@ -0,0 +1,32 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { bokioAuth } from '../common/auth';
+import { makeRequest } from '../common/client';
+import { HttpMethod } from '@agnocon/pieces-common';
+
+export const getAJournalEntry = createAction({
+  auth: bokioAuth,
+  name: 'getAJournalEntry',
+  displayName: 'Get a journal entry',
+  description: 'Retrieve a specific journal entry by its ID',
+  audience: 'both',
+  aiMetadata: { description: 'Retrieves a single journal entry from a Bokio company by its UUID. Use when you already have the journal entry ID and need its full bookkeeping details. Idempotent read-only lookup.', idempotent: true },
+  props: {
+    journalEntryId: Property.ShortText({
+      displayName: 'Journal Entry ID',
+      description: 'UUID of the journal entry',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const { journalEntryId } = context.propsValue;
+    const { api_key, companyId } = context.auth.props;
+
+    const response = await makeRequest(
+      api_key,
+      HttpMethod.GET,
+      `/companies/${companyId}/journal-entries/${journalEntryId}`
+    );
+
+    return response;
+  },
+});

package/src/lib/actions/get-an-invoice.ts

@@ -0,0 +1,32 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { bokioAuth } from '../common/auth';
+import { makeRequest } from '../common/client';
+import { HttpMethod } from '@agnocon/pieces-common';
+
+export const getAnInvoice = createAction({
+  auth: bokioAuth,
+  name: 'getAnInvoice',
+  displayName: 'Get an invoice',
+  description: 'Retrieve a specific invoice by its ID',
+  audience: 'both',
+  aiMetadata: { description: 'Retrieves a single invoice from a Bokio company by its invoice ID. Use when you already have the invoice ID and need its full details. Idempotent read-only lookup.', idempotent: true },
+  props: {
+    invoiceId: Property.ShortText({
+      displayName: 'Invoice ID',
+      description: 'The ID of the invoice to retrieve',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const { invoiceId } = context.propsValue;
+    const { api_key, companyId } = context.auth.props;
+
+    const response = await makeRequest(
+      api_key,
+      HttpMethod.GET,
+      `/companies/${companyId}/invoices/${invoiceId}`
+    );
+
+    return response;
+  },
+});

package/src/lib/actions/get-draft-invoice-by-customer-name.ts

@@ -0,0 +1,78 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { bokioAuth } from '../common/auth';
+import { makeRequest } from '../common/client';
+import { HttpMethod } from '@agnocon/pieces-common';
+
+export const getDraftInvoiceByCustomerName = createAction({
+  auth: bokioAuth,
+  name: 'getDraftInvoiceByCustomerName',
+  displayName: 'Get Draft Invoice by Customer Name',
+  description: 'Get all draft invoices for a customer by customer name',
+  audience: 'both',
+  aiMetadata: { description: 'Looks up a Bokio customer by exact name and returns their draft invoices with pagination. Use when you have a customer name (not an ID) and want their pending draft invoices; returns an empty result if no customer matches. Idempotent read-only lookup.', idempotent: true },
+  props: {
+    customerName: Property.ShortText({
+      displayName: 'Customer Name',
+      description: 'Name of the customer to find draft invoices for',
+      required: true,
+    }),
+    page: Property.Number({
+      displayName: 'Page',
+      description: 'Page number (defaults to 1)',
+      required: false,
+    }),
+    pageSize: Property.Number({
+      displayName: 'Page Size',
+      description: 'Number of items per page (max 100, defaults to 25)',
+      required: false,
+    }),
+  },
+  async run(context) {
+    const { customerName, page, pageSize } = context.propsValue;
+    const { api_key, companyId } = context.auth.props;
+
+    // First, find the customer by name
+    const customerSearchParams = new URLSearchParams();
+    customerSearchParams.append('page', '1');
+    customerSearchParams.append('pageSize', '100');
+    customerSearchParams.append('query', `name=='${customerName}'`);
+
+    const customerUrl = `/companies/${companyId}/customers?${customerSearchParams.toString()}`;
+    const customerResponse = await makeRequest(api_key, HttpMethod.GET, customerUrl);
+
+    if (!customerResponse.items || customerResponse.items.length === 0) {
+      return {
+        message: `No customer found with name: ${customerName}`,
+        items: [],
+      };
+    }
+
+    const customerId = customerResponse.items[0].id;
+
+    // Now fetch draft invoices for this customer
+    const invoiceParams = new URLSearchParams();
+    if (page !== undefined && page !== null) {
+      invoiceParams.append('page', String(page));
+    } else {
+      invoiceParams.append('page', '1');
+    }
+
+    if (pageSize !== undefined && pageSize !== null) {
+      invoiceParams.append('pageSize', String(pageSize));
+    } else {
+      invoiceParams.append('pageSize', '25');
+    }
+
+    // Filter for draft invoices with matching customer
+    invoiceParams.append('query', `status==draft&&customerRef==${customerId}`);
+
+    const invoiceUrl = `/companies/${companyId}/invoices?${invoiceParams.toString()}`;
+    const invoiceResponse = await makeRequest(api_key, HttpMethod.GET, invoiceUrl);
+
+    return {
+      customerName: customerResponse.items[0].name,
+      customerId,
+      ...invoiceResponse,
+    };
+  },
+});

package/src/lib/actions/update-an-invoice.ts

@@ -0,0 +1,127 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { bokioAuth } from '../common/auth';
+import { makeRequest } from '../common/client';
+import { HttpMethod } from '@agnocon/pieces-common';
+import { invoiceIdDropdown } from '../common/props';
+
+export const updateAnInvoice = createAction({
+  auth: bokioAuth,
+  name: 'updateAnInvoice',
+  displayName: 'Update an invoice',
+  description: 'Updates an existing draft invoice in Bokio',
+  audience: 'both',
+  aiMetadata: { description: 'Updates an existing draft invoice in Bokio, identified by invoice ID, replacing fields such as type, customer, dates, currency, and the full line-items list (passed as a JSON array). Use to modify an invoice that already exists rather than create one. Idempotent — repeating the same update yields the same invoice state.', idempotent: true },
+  props: {
+    invoiceId: invoiceIdDropdown,
+    invoiceType: Property.StaticDropdown({
+      displayName: 'Invoice Type',
+      description: 'Type of invoice',
+      required: false,
+      options: {
+        options: [
+          { label: 'Invoice', value: 'invoice' },
+          { label: 'Cash Invoice', value: 'cashInvoice' },
+        ],
+      },
+    }),
+    customerRef: Property.ShortText({
+      displayName: 'Customer ID',
+      description: 'UUID of the customer',
+      required: false,
+    }),
+    invoiceDate: Property.ShortText({
+      displayName: 'Invoice Date',
+      description: 'Invoice date (YYYY-MM-DD)',
+      required: true,
+    }),
+    dueDate: Property.ShortText({
+      displayName: 'Due Date',
+      description: 'Due date (YYYY-MM-DD)',
+      required: true,
+    }),
+    orderNumberReference: Property.ShortText({
+      displayName: 'Order Number Reference',
+      description: 'The order number associated with the invoice',
+      required: false,
+    }),
+    currency: Property.ShortText({
+      displayName: 'Currency',
+      description: 'ISO 4217 currency code (e.g., SEK, EUR, USD)',
+      required: false,
+    }),
+    currencyRate: Property.Number({
+      displayName: 'Currency Rate',
+      description: 'Currency rate',
+      required: false,
+    }),
+    lineItemsJson: Property.LongText({
+      displayName: 'Line Items (JSON)',
+      description:
+        'Line items as JSON array. Each item should have: itemRef (object with id), description, quantity, unitPrice, unit, itemType (PRODUCT or SERVICE), vat',
+      required: false,
+    }),
+  },
+  async run(context) {
+    const {
+      invoiceId,
+      invoiceType,
+      customerRef,
+      invoiceDate,
+      dueDate,
+      orderNumberReference,
+      currency,
+      currencyRate,
+      lineItemsJson,
+    } = context.propsValue;
+    const { api_key, companyId } = context.auth.props;
+
+    const body: any = {};
+
+    if (invoiceType) {
+      body.type = invoiceType;
+    }
+
+    if (customerRef) {
+      body.customerRef = {
+        id: customerRef,
+      };
+    }
+
+    if (invoiceDate) {
+      body.invoiceDate = invoiceDate;
+    }
+
+    if (dueDate) {
+      body.dueDate = dueDate;
+    }
+
+    if (orderNumberReference) {
+      body.orderNumberReference = orderNumberReference;
+    }
+
+    if (currency) {
+      body.currency = currency;
+    }
+
+    if (currencyRate !== undefined && currencyRate !== null) {
+      body.currencyRate = currencyRate;
+    }
+
+    if (lineItemsJson) {
+      try {
+        body.lineItems = JSON.parse(lineItemsJson);
+      } catch {
+        throw new Error('Invalid JSON format for line items');
+      }
+    }
+
+    const response = await makeRequest(
+      api_key,
+      HttpMethod.PUT,
+      `/companies/${companyId}/invoices/${invoiceId}`,
+      body
+    );
+
+    return response;
+  },
+});

package/src/lib/common/auth.ts

@@ -0,0 +1,44 @@
+import { PieceAuth, Property } from '@agnocon/pieces-framework';
+import { makeRequest } from './client';
+import { httpClient, HttpMethod } from '@agnocon/pieces-common';
+
+export const bokioAuth = PieceAuth.CustomAuth({
+  displayName: 'Bokio API Key',
+  description: 'Bokio API Key is required to authenticate requests to Bokio',
+  required: true,
+  props: {
+    companyId: Property.ShortText({
+      displayName: 'Company ID',
+      description: 'Enter your Bokio Company ID ',
+      required: true,
+    }),
+    api_key: Property.ShortText({
+      displayName: 'API Key',
+      description: 'Enter your Bokio API Key',
+      required: true,
+    }),
+  },
+  validate: async ({ auth }) => {
+    if (auth) {
+      try {
+        await makeRequest(
+          auth.api_key,
+          HttpMethod.GET,
+          `/companies/${auth.companyId}/journal-entries`
+        );
+        return {
+          valid: true,
+        };
+      } catch (e) {
+        return {
+          valid: false,
+          error: 'Invalid Api Key',
+        };
+      }
+    }
+    return {
+      valid: false,
+      error: 'Invalid Api Key',
+    };
+  },
+});

package/src/lib/common/client.ts

@@ -0,0 +1,25 @@
+import { HttpMethod, httpClient } from '@agnocon/pieces-common';
+
+export const BASE_URL = `https://api.bokio.se/v1`;
+
+export async function makeRequest(
+  api_key: string,
+  method: HttpMethod,
+  path: string,
+  body?: unknown
+) {
+  try {
+    const response = await httpClient.sendRequest({
+      method,
+      url: `${BASE_URL}${path}`,
+      headers: {
+        Authorization: `Bearer ${api_key}`,
+        'Content-Type': 'application/json',
+      },
+      body,
+    });
+    return response.body;
+  } catch (error: any) {
+    throw new Error(`Unexpected error: ${error.message || String(error)}`);
+  }
+}

package/src/lib/common/props.ts

@@ -0,0 +1,136 @@
+import { Property } from '@agnocon/pieces-framework';
+import { makeRequest } from './client';
+import { bokioAuth } from './auth';
+import { HttpMethod } from '@agnocon/pieces-common';
+
+export const invoiceIdDropdown = Property.Dropdown({
+  auth: bokioAuth,
+  displayName: 'Invoice',
+  description: 'Select the invoice',
+  required: true,
+  refreshers: [],
+  options: async ({ auth }) => {
+    if (!auth) {
+      return {
+        disabled: true,
+        options: [],
+      };
+    }
+    try {
+      const response = await makeRequest(
+        auth.props.api_key,
+        HttpMethod.GET,
+        `/companies/${auth.props.companyId}/invoices?limit=100`
+      );
+
+      const options = response.items.map((invoice: any) => ({
+        label: `#${invoice.invoiceNumber} - ${invoice.customerRef.customerName}`,
+        value: invoice.id,
+      }));
+
+      return {
+        disabled: false,
+        options,
+      };
+    } catch (error) {
+      return {
+        disabled: true,
+        options: [],
+      };
+    }
+  },
+});
+
+export const unitTypeDropdown = Property.StaticDropdown({
+  displayName: 'Unit Type',
+  description: 'Unit type for the item',
+  required: false,
+  options: {
+    options: [
+      { label: 'Unspecified', value: 'unspecified' },
+      { label: 'Piece', value: 'piece' },
+      { label: 'Hour', value: 'hour' },
+      { label: 'Day', value: 'day' },
+      { label: 'Month', value: 'month' },
+      { label: 'Kilogram', value: 'kilogram' },
+      { label: 'Gram', value: 'gram' },
+      { label: 'Liter', value: 'liter' },
+      { label: 'Meter', value: 'meter' },
+      { label: 'Centimeter', value: 'centimeter' },
+      { label: 'Millimeter', value: 'millimeter' },
+      { label: 'Meter Squared', value: 'meterSquared' },
+      { label: 'Meter Cubic', value: 'meterCubic' },
+      { label: 'Mile', value: 'mile' },
+      { label: 'Kilometer', value: 'kilometer' },
+      { label: 'Gigabyte', value: 'gigabyte' },
+      { label: 'Hectar', value: 'hectar' },
+      { label: 'Words', value: 'words' },
+      { label: 'Year', value: 'year' },
+      { label: 'Week', value: 'week' },
+      { label: 'Minute', value: 'minute' },
+      { label: 'Megabyte', value: 'megabyte' },
+      { label: 'Ton', value: 'ton' },
+    ],
+  },
+});
+
+export const lineItemsProps = Property.DynamicProperties({
+  auth: bokioAuth,
+  displayName: 'Item Details',
+  description: 'Configure item details based on item type',
+  required: false,
+  refreshers: ['itemType'],
+  props: async ({ itemType }) => {
+    const properties: Record<string, any> = {
+      description: Property.ShortText({
+        displayName: 'Description',
+        description: 'Description of the line item',
+        required: true,
+      }),
+    };
+
+    // Only show pricing fields for sales items
+    if (itemType === 'salesItem') {
+      properties['itemRefId'] = Property.ShortText({
+        displayName: 'Item Reference ID',
+        description: 'UUID of the item reference',
+        required: false,
+      });
+
+      properties['productType'] = Property.StaticDropdown({
+        displayName: 'Product Type',
+        description: 'Type of product',
+        required: true,
+        options: {
+          options: [
+            { label: 'Goods', value: 'goods' },
+            { label: 'Service', value: 'service' },
+          ],
+        },
+      });
+
+      properties['unitType'] = unitTypeDropdown;
+
+      properties['quantity'] = Property.Number({
+        displayName: 'Quantity',
+        description: 'Quantity of the item',
+        required: true,
+        defaultValue: 1,
+      });
+
+      properties['unitPrice'] = Property.Number({
+        displayName: 'Unit Price',
+        description: 'Price per unit',
+        required: true,
+      });
+
+      properties['taxRate'] = Property.Number({
+        displayName: 'Tax Rate',
+        description: 'Tax rate in percentage (e.g., 25 for 25%)',
+        required: false,
+      });
+    }
+
+    return properties;
+  },
+});