The modules set error in any error. The modules provide the success method which returns true on success or false if there was an error. The user of the module is expected to check success. The error method returns the error value so that the user can understand why success is false.

I see most of your Business::Stripe::Webhook module's methods begin by clearing the module error property via:

$self->{'error'} = '';
[download]

I also noticed your get_subscription method does not do this. Is this a bug?

In case it helps, another minor issue I noticed is the return value of your check_signature method is not documented. Examining the code indicates it can return 1 or 0 or undef. It would be good to document this method's return value and the difference between returning 0 and undef.

presumably to avoid confusion from a spurious error property set by an earlier method call. Is that right?

Spot on...

I also noticed your get_subscription method does not do this. Is this a bug?

Well spotted, yes it is a bug. It has been corrected in my code locally. Although I suppose I should have done that on GitHub!

In case it helps, another minor issue I noticed is the return value of your check_signature method is not documented

It helps a lot thank you.
As it says in the documentation, there shouldn't be any need to call this method. Originally I was going to have it as a private method but decided that there may be a use case for checking Stripe signatures outside of the workflow that's documented. So, in the end it became a public method.

The return values have now been added to POD in my local copy.

> It helps a lot thank you

You're welcome Bod. Always looking out for you.

In fact, I've just received an urgent alert that a small red car has been swallowed up by a huge sinkhole in Coventry UK -- Bod, I urge you to avoid the Sewall Highway if you possibly can (hope it wasn't your car in the sinkhole :)

G'day Bod,

Here's a few things that I do which you may find useful (possibly in code outside the Business::Stripe:: namespace). In general, these are intended to promote consistency and reduce coding effort.

Have a small number of routines to output messages (e.g. print_error(), print_warning() and so on). These accept a format for the message along with a variable number of arguments. Here's a very rough, off-the-top-of-my-head example:

sub print_error {
    my ($fmt, @args) = @_;
    die 'ERROR: ', sprintf $fmt, @args;
}
[download]

Define each format once only. This could be globally as a constant, specific to a subroutine as a state variable, or using some other method; you may even use a combination of these. Here's some arbitrary examples of formats:

'Start date (%s) cannot be after end date (%s)'
'Postcode (%s) contains invalid characters'
'ID is a required field'
[download]

You can paste these formats directly into the DIAGNOSTICS (or equivalent) section of your POD. See perldiag for a multitude of examples of this type of documentation.

Where possible, I try to collect as many problem reports as possible into a single message. So, if the above three example formats were needed, the user would know to make changes to date, postcode and ID fields from a single piece of feedback, rather than being drip-fed one problem at a time.

How messages are presented will very much depend on the interface. With GUIs (web or other) I often find a small [i] button can provide information about what exactly is required in a field. A popup panel can list the problems and also contain the same [i] buttons for ease of reference.

Very helpful, thanks Ken

I have been trying (not always successfully) to have a small number (preferably one) to output everything...this includes a single method as a wrapper around the process method of Template.

It's reassuring to read your advice which is generally aligned with what I'm striving to do.

The return values in that are canonically (in JavaScript terms) objects, i.e. in Perl terms hash-refs, which have at least one of data and/or errors. It does exception-catching to turn those into errors entries.

I mention this because it is "guaranteed" (with the usual caveats) to return JSON. I would suggest your web service should adopt a similar philosophy, so that 500s aren't possible, and an appropriate return to the user always happens.