Api Support Classes Laravel Package

Product Decisions This Supports

• Build vs. buy vs. borrow for the API contract layer. This package is a "borrow" option: a small, permissively licensed set of support classes extracted from Firefly III, a mature self-hosted personal-finance application. The decision it informs is whether we define our own API vocabulary (resource types, transaction/account enumerations, webhook triggers, error shapes) or adopt a vocabulary that already runs in production somewhere else.
• Integration roadmap sequencing. If our roadmap contains an importer, a connector, a companion mobile client, or webhook delivery, a shared vocabulary package lets us pull that milestone forward — the contract-level work is already done, so estimation collapses to transport and persistence rather than schema debates.
• Interoperability with the Firefly III ecosystem. Any feature that must speak to Firefly III (data importer, third-party sync, migration tooling) is materially cheaper if we consume the same classes rather than reverse-engineering magic strings from documentation.
• Shared-kernel architecture between our own services. The pattern itself is the decision: extracting a tiny dependency-free package that both an API app and a worker/importer depend on, so enums and validation rules cannot drift. We can either adopt this one or copy its shape.
• Explicitly not a driver for: pricing, UX, data-model ownership, storage strategy, or anything above the API contract layer. This package does not provide controllers, routing, serialization, or HTTP machinery — treating it as an "API framework" would be a scoping error.

When to Consider This Package

Adopt (or vendor) when:

• You are building inside the Firefly III ecosystem — an importer, connector, plugin, or companion app. Here it is close to mandatory and the alternative is duplicating constants badly.
• You are building a Laravel/PHP finance or accounting API and want a pre-existing, battle-tested domain vocabulary instead of inventing one. The value is in agreeing on names once, not in the code volume.
• You need payloads that must match Firefly III conventions byte-for-byte (webhook triggers, transaction types, account roles).
• You want a worked example of the shared-kernel pattern for two of your own services — even if you don't depend on it, read it before designing yours.

Look elsewhere when:

• Adoption risk is unpriced by the metrics. Zero stars and zero dependents means no ecosystem pressure to preserve backward compatibility; the API surface moves with one maintainer's roadmap. Pin the version, vendor the source, and cover it with your own contract tests.
• You need the transport layer. This is support classes, not a framework. Controllers, middleware, pagination, and serialization remain your problem.
• Your domain diverges from Firefly III's. Double-entry ledgers, multi-currency revaluation, or atypical account hierarchies will fight a vocabulary built for a specific product's model.
• You are not on PHP/Laravel. The value drops to near zero outside that stack.
• You require vendor support or semver guarantees. There is no SLA here.
• A general-purpose tool already covers it — Laravel API Resources, OpenAPI codegen, or an established enum/schema package may be a better default when you are not integrating with this specific ecosystem.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a tactical accelerator, not a strategic dependency. It lets us reuse API vocabulary that already runs in a mature open-source finance application instead of spending engineering days defining and re-litigating our own. The cost is near-zero and the downside is bounded: the package is small, permissively licensed, and easy to vendor and replace if it stalls. The low star count and zero dependents mean we should not treat it as an industry standard — we should treat it as a well-formed starting point we own the risk on.

For engineering (the real argument): This is a shared kernel. It prevents drift between an API service and an importer/worker that must agree on enumerations and validation rules — drift that otherwise surfaces as silent data corruption rather than a compile error. It is small, readable, has no runtime overhead, and is easy to pin and vendor. Mitigations: pin the version, vendor the source into our tree if we ship it, and write contract tests around the constants we actually depend on so an upstream rename fails our build rather than our customers' integrations.

For product (the framing that matters): The honest pitch is "we are buying time on the contract layer, not buying a feature." It does not unlock a roadmap item on its own; it removes a week of vocabulary arguments in front of the item that does. If we are not integrating with Firefly III and not building a finance-domain API, the correct answer is to skip it and spend the review time elsewhere.